diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-09-19 01:45:44 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-09-19 01:45:44 +0000 |
| commit | 85dc423f7090da0a52c73eb66faf22ddb20efff9 (patch) | |
| tree | 9160f299afd8c80c038f08e1545be119f5e3f1e1 /doc/user/project | |
| parent | 15c2c8c66dbe422588e5411eee7e68f1fa440bb8 (diff) | |
| download | gitlab-ce-85dc423f7090da0a52c73eb66faf22ddb20efff9.tar.gz | |
Add latest changes from gitlab-org/gitlab@13-4-stable-ee
Diffstat (limited to 'doc/user/project')
77 files changed, 1011 insertions, 670 deletions
diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md index c4a6aea807c..98584a939ea 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -14,6 +14,9 @@ For more details, see If you want to update attributes across multiple issues or merge requests, you can do it by bulk editing them, that is, editing them together. +NOTE: **Note:** +Only the items visible on the current page are selected for bulk editing (up to 20). +  ## Bulk edit issues at the project level diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 852baf1f628..afce3869cbf 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -48,9 +48,9 @@ Canary deployments require that you properly configure Deploy Boards: template for canary deployments that GitLab provides. Depending on the deploy, the label should be either `stable` or `canary`. -Usually, `stable` and blank or missing label means the same thing, and `canary` -or any other track means canary/temporary. -This allows GitLab to discover whether deployment is stable or canary (temporary). +GitLab assumes the track label is `stable` if the label is blank or missing. +Any other track label is considered `canary` (temporary). +This allows GitLab to discover whether a deployment is stable or canary (temporary). Once all of the above are set up and the pipeline has run at least once, navigate to the environments page under **Pipelines > Environments**. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index d5713f20257..b3b1b51a543 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -141,7 +141,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: 1. Choose your cluster's settings: - **Kubernetes cluster name** - The name you wish to give the cluster. - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope) to this cluster. - - **Kubernetes version** - The Kubernetes version to use. Currently the only version supported is 1.14. + - **Kubernetes version** - The [Kubernetes version](index.md#supported-cluster-versions) to use. - **Service role** - Select the **EKS IAM role** you created earlier to allow Amazon EKS and the Kubernetes control plane to manage AWS resources on your behalf. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index e4a750084c9..18d9fa67ee1 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -110,10 +110,10 @@ GitLab creates the following resources for ABAC clusters. | Environment namespace | `ServiceAccount` | Uses namespace of environment | Deploying to a cluster | | Environment namespace | `Secret` | Token for environment ServiceAccount | Deploying to a cluster | -### Security of GitLab Runners +### Security of runners -GitLab Runners have the [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#the-privileged-mode) -enabled by default, which allows them to execute special commands and running +Runners have the [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#the-privileged-mode) +enabled by default, which allows them to execute special commands and run Docker in Docker. This functionality is needed to run some of the [Auto DevOps](../../../topics/autodevops/index.md) jobs. This implies the containers are running in privileged mode and you should, @@ -124,14 +124,14 @@ turn can do almost everything that the host can do. Be aware of the inherent security risk associated with performing `docker run` operations on arbitrary images as they effectively have root access. -If you don't want to use GitLab Runner in privileged mode, either: +If you don't want to use a runner in privileged mode, either: -- Use shared Runners on GitLab.com. They don't have this security issue. -- Set up your own Runners using the configuration described at - [Shared Runners](../../gitlab_com/index.md#shared-runners). This involves: +- Use shared runners on GitLab.com. They don't have this security issue. +- Set up your own runners using the configuration described at + [shared runners](../../gitlab_com/index.md#shared-runners). This involves: 1. Making sure that you don't have it installed via [the applications](index.md#installing-applications). - 1. Installing a Runner + 1. Installing a runner [using `docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html). ## Create new cluster @@ -206,7 +206,7 @@ To add a Kubernetes cluster to your project, group, or instance: apiVersion: v1 kind: ServiceAccount metadata: - name: gitlab-admin + name: gitlab namespace: kube-system --- apiVersion: rbac.authorization.k8s.io/v1beta1 @@ -219,7 +219,7 @@ To add a Kubernetes cluster to your project, group, or instance: name: cluster-admin subjects: - kind: ServiceAccount - name: gitlab-admin + name: gitlab namespace: kube-system ``` @@ -245,23 +245,23 @@ To add a Kubernetes cluster to your project, group, or instance: Output: ```shell - serviceaccount "gitlab-admin" created + serviceaccount "gitlab" created clusterrolebinding "gitlab-admin" created ``` - 1. Retrieve the token for the `gitlab-admin` service account: + 1. Retrieve the token for the `gitlab` service account: ```shell - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab | awk '{print $1}') ``` Copy the `<authentication_token>` value from the output: ```yaml - Name: gitlab-admin-token-b5zv4 + Name: gitlab-token-b5zv4 Namespace: kube-system Labels: <none> - Annotations: kubernetes.io/service-account.name=gitlab-admin + Annotations: kubernetes.io/service-account.name=gitlab kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 Type: kubernetes.io/service-account-token diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 98078854050..8d188f00ceb 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -22,8 +22,8 @@ Using the GitLab project Kubernetes integration, you can: - Detect and [monitor Kubernetes](#monitoring-your-kubernetes-cluster). - Use it with [Auto DevOps](#auto-devops). - Use [Web terminals](#web-terminals). -- Use [Deploy Boards](#deploy-boards-premium). **(PREMIUM)** -- Use [Canary Deployments](#canary-deployments-premium). **(PREMIUM)** +- Use [Deploy Boards](#deploy-boards). **(PREMIUM)** +- Use [Canary Deployments](#canary-deployments). **(PREMIUM)** - View [Logs](#viewing-pod-logs). - Run serverless workloads on [Kubernetes with Knative](serverless/index.md). @@ -46,11 +46,11 @@ version. The range of supported versions is based on the evaluation of: Currently, GitLab supports the following Kubernetes versions: +- 1.17 - 1.16 - 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. diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md index 5b9f776080b..a15660051f7 100644 --- a/doc/user/project/clusters/securing.md +++ b/doc/user/project/clusters/securing.md @@ -36,7 +36,7 @@ At a high level, the required steps include the following: Minimum requirements (depending on the GitLab Manage Application you want to install): - Your cluster is connected to GitLab (ModSecurity, Cilium, and Falco). -- At least one GitLab Runner is installed (Cilium and Falco only). +- At least one runner is installed (Cilium and Falco only). ### Understanding how GitLab Managed Apps are installed @@ -62,7 +62,7 @@ deployment logs. The Web Application Firewall feature uses this installation met However, the next generation of GitLab Managed Apps V2 ([CI/CD-based GitLab Managed Apps](https://gitlab.com/groups/gitlab-org/-/epics/2103)) don't use Sidekiq to deploy. All the applications are deployed using a GitLab CI/CD pipeline and -therefore GitLab Runners. +therefore, by runners. ```mermaid sequenceDiagram @@ -91,14 +91,14 @@ the Web Application Firewall from the project or group Kubernetes page. Note that your project doesn't have to be hosted or deployed through GitLab. You can manage a cluster independent of the applications that use the cluster. -## Set up a GitLab Runner +## Set up a runner -To install CI/CD-based GitLab Managed Apps, a pipeline using a GitLab Runner must be running in -GitLab. You can [install a GitLab Runner](../../clusters/applications.md#gitlab-runner) +To install CI/CD-based GitLab Managed Apps, a pipeline using a runner must be running in +GitLab. You can [install a runner](../../clusters/applications.md#gitlab-runner) in the Kubernetes cluster added in the previous step, or use one of the shared runners provided by GitLab if you're using GitLab.com. -With your cluster connected to GitLab and a GitLab Runner in place, you can proceed to the next +With your cluster connected to GitLab and a runner in place, you can proceed to the next steps and start installing the Cilium and Falco GitLab Managed Apps to secure your applications hosted on this cluster. diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 6af08b06294..1157c2c5632 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -52,7 +52,7 @@ To run Knative on GitLab, you will need: The simplest way to get started is to add a cluster using GitLab's [GKE integration](../add_remove_clusters.md). The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. 1. **GitLab Runner:** A runner is required to run the CI jobs that will deploy serverless - applications or functions onto your cluster. You can install the GitLab Runner + applications or functions onto your cluster. You can install GitLab Runner onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information. 1. **Domain Name:** Knative will provide its own load balancer using Istio. It will provide an external IP address or hostname for all the applications served by Knative. You will be prompted to enter a diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index be34053cdc7..f56673e69b7 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -26,10 +26,9 @@ Enable code intelligence for a project by adding a GitLab CI/CD job to the proje ```yaml code_navigation: - image: golang:1.14.0 + image: sourcegraph/lsif-go:v1 allow_failure: true # recommended script: - - go get github.com/sourcegraph/lsif-go/cmd/lsif-go - lsif-go artifacts: reports: @@ -40,38 +39,18 @@ The generated LSIF file must be less than 170MiB. After the job succeeds, code intelligence data can be viewed while browsing the code: - + ## Find references > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217392) in GitLab 13.2. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/225621) on GitLab 13.3. -> - It's enabled on GitLab.com. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235735) in GitLab 13.4. To find where a particular object is being used, you can see links to specific lines of code under the **References** tab:  -### Enable or disable find references - -Find references is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to disable it for your instance. - -To disable it: - -```ruby -Feature.disable(:code_navigation_references) -``` - -To enable it: - -```ruby -Feature.enable(:code_navigation_references) -``` - ## Language support Generating an LSIF file requires a language server indexer implementation for the diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index dbe3f3dc891..730a9ada428 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -9,7 +9,6 @@ type: reference > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. -> - [Support for group namespaces](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) added in GitLab Starter 12.1. > - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9. ## Introduction @@ -74,7 +73,7 @@ Once you've added Code Owners to a project, you can configure it to be used for merge request approvals: - As [merge request eligible approvers](merge_requests/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)** +- As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** NOTE: **Note:** Developer or higher [permissions](../permissions.md) are required in order to @@ -88,11 +87,11 @@ While the `CODEOWNERS` file can be used in addition to Merge Request [Approval R it can also be used as the sole driver of merge request approvals (without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules)). To do so, create the file in one of the three locations specified above and -set the code owners as required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium). +set the code owners as required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) to specify the actual owners and granular permissions. -Using Code Owners in conjunction with [Protected Branches](protected_branches.md#protected-branches-approval-by-code-owners-premium) +Using Code Owners in conjunction with [Protected Branches](protected_branches.md#protected-branches-approval-by-code-owners) will prevent any user who is not specified in the `CODEOWNERS` file from pushing changes for the specified files/paths, even if their role is included in the **Allowed to push** column. This allows for a more inclusive push strategy, as @@ -108,49 +107,58 @@ in the `.gitignore` file followed by one or more of: - A user's `@username`. - A user's email address. - The `@name` of one or more groups that should be owners of the file. +- Lines starting with `#` are escaped. -Groups must be added as [members of the project](members/index.md), -or they will be ignored. +The order in which the paths are defined is significant: the last pattern that +matches a given path will be used to find the code owners. -Starting in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/32432), -you can additionally specify groups or subgroups from the project's upper group -hierarchy as potential code owners, without having to invite them specifically -to the project. Groups outside the project's hierarchy or children beneath the -hierarchy must still be explicitly invited to the project in order to show as -Code Owners. +### Groups as Code Owners -For example, consider the following hierarchy for the example project -`example_project`: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab Starter 12.1. +> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.0. -```plaintext -group >> sub-group >> sub-subgroup >> example_project >> file.md -``` +Groups and subgroups members are inherited as eligible Code Owners to a +project, as long as the hierarchy is respected. + +For example, consider a given group called "Group X" (slug `group-x`) and a +"Subgroup Y" (slug `group-x/subgroup-y`) that belongs to the Group X, and +suppose you have a project called "Project A" within the group and a +"Project B" within the subgroup. -Any of the following groups would be eligible to be specified as code owners: +The eligible Code Owners to Project B are both the members of the Group X and +the Subgroup Y. And the eligible Code Owners to the Project A are just the +members of the Group X, given that Project A doesn't belong to the Subgroup Y: -- `@group` -- `@group/sub-group` -- `@group/sub-group/sub-subgroup` + -In addition, any groups that have been invited to the project using the -**Members** tool will also be recognized as eligible code owners. +But you have the option to [invite](members/share_project_with_groups.md) +the Subgroup Y to the Project A so that their members also become eligible +Code Owners: -The order in which the paths are defined is significant: the last -pattern that matches a given path will be used to find the code -owners. + -Starting a line with a `#` indicates a comment. This needs to be -escaped using `\#` to address files for which the name starts with a -`#`. +Once invited, any member (`@user`) of the group or subgroup can be set +as Code Owner to files of the Project A or B, as well as the entire Group X +(`@group-x`) or Subgroup Y (`@group-x/subgroup-y`), as exemplified below: + +```plaintext +# A member of the group or subgroup as Code Owner to a file +file.md @user + +# All group members as Code Owners to a file +file.md @group-x + +# All subgroup members as Code Owners to a file +file.md @group-x/subgroup-y + +# All group and subgroup members as Code Owners to a file +file.md @group-x @group-x/subgroup-y +``` ### Code Owners Sections **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. -> - It's deployed behind a feature flag, enabled by default. -> - It's enabled on GitLab.com. -> - It can be enabled or disabled per-project. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-code-owner-sections-core-only). **(CORE ONLY)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2 behind a feature flag, enabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. Code Owner rules can be grouped into named sections. This allows for better organization of broader categories of Code Owner rules to be applied. @@ -212,28 +220,6 @@ the rules for "Groups" and "Documentation" sections:  -#### Enable or disable Code Owner Sections **(CORE ONLY)** - -Sections is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to disable it for your instance. - -To disable it: - -```ruby -Feature.disable(:sectional_codeowners) -``` - -To enable it: - -```ruby -Feature.enable(:sectional_codeowners) -``` - -CAUTION: **Caution:** -Disabling Sections will **not** refresh Code Owner Approval Rules on existing merge requests. - ## Example `CODEOWNERS` file ```plaintext diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 50fb24b555b..8146f39ef87 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -81,8 +81,8 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations) and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab/-/issues/4584). -1. [Configure GitLab Runner](../../ci/runners/README.md) with the [Docker](https://docs.gitlab.com/runner/executors/docker.html) or - [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) executor. +1. [Configure GitLab Runner](../../ci/runners/README.md) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or + [`kubernetes`](https://docs.gitlab.com/runner/executors/kubernetes.html) executor. 1. Configure the [Kubernetes integration](clusters/index.md) in your project for the cluster. The Kubernetes namespace is of particular note as you will need it for your deployment scripts (exposed by the `KUBE_NAMESPACE` env variable). @@ -105,6 +105,8 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ re-deploy your application. If you are using Auto DevOps, this will be done automatically and no action is necessary. + If you are using GCP to manage clusters, you can see the deployment details in GCP itself by going to **Workloads > deployment name > Details**: +  Once all of the above are set up and the pipeline has run at least once, diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index ed80e5f6a32..6fd33901621 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -1,108 +1,230 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- -# File Locking **(PREMIUM)** +# File Locking **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in [GitLab Premium](https://about.gitlab.com/pricing/) 8.9. +Preventing wasted work caused by unresolvable merge conflicts requires +a different way of working. This means explicitly requesting write permissions, +and verifying no one else is editing the same file before you start. -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. +Although branching strategies usually work well enough for source code and +plain text because different versions can be merged together, they do not work +for 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. +When file locking is setup, lockable files are **read only** by default. -## Overview +When a file is locked, only the user who locked the file may modify it. This +user is said to "hold the lock" or have "taken the lock", since only one user +can lock a file at a time. When a file or directory is unlocked, the user is +said to have "released the lock". -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. With GitLab Premium, File -Locking helps you avoid merge conflicts and better manage your binary -files by preventing everyone, except you, from modifying a specific file -or entire directory. +GitLab supports two different modes of file locking: -## Use-cases +- [Exclusive file locks](#exclusive-file-locks) for binary files: done **through + the command line** with Git LFS and `.gitattributes`, it prevents locked + files from being modified on any branch. **(CORE)** +- [Default branch locks](#default-branch-file-and-directory-locks): done + **through the GitLab UI**, it prevents locked files and directories being + modified on the default branch. **(PREMIUM)** -The file locking feature is useful in situations when: +## Permissions -- Multiple people are working on the same file and you want to avoid merge - conflicts. -- Your repository contains binary files in which situation there is no easy - way to tell the diff between yours and your colleagues' changes. -- Prevent design assets from being overwritten. +Locks can be created by any person who has at least +[Developer permissions](../permissions.md) to the repository. -Locked directories are locked recursively, which means that everything that -lies under them is also locked. +Only the user who locked the file or directory can edit locked files. Others +users will be prevented from modifying locked files by pushing, merging, +or any other means, and will be shown an error like: `The path '.gitignore' is +locked by Administrator`. -## Locking a file or a directory +## Exclusive file locks -NOTE: **Note:** -Locking only works for the default branch you have set in the project's settings -(usually `master`). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35856) in GitLab 10.5. -To lock a file: +This process allows you to lock single files or file extensions and it is +done through the command line. It doesn't require GitLab paid subscriptions. -1. Navigate to your project's **Repository > Files**. -1. Pick the file you want to lock. -1. Click the "Lock" button. +Git LFS is well known for tracking files to reduce the storage of +Git repositories, but it can also be user for [locking files](https://github.com/git-lfs/git-lfs/wiki/File-Locking). +This is the method used for Exclusive File Locks. -  +### Install Git LFS + +Before getting started, make sure you have [Git LFS installed](../../topics/git/lfs/index.md) in your computer. Open a terminal window and run: + +```shell +git-lfs --version +``` + +If it doesn't recognize this command, you'll have to install it. There are +several [installation methods](https://git-lfs.github.com/) that you can +choose according to your OS. To install it with Homebrew: + +```shell +brew install git-lfs +``` + +Once installed, **open your local repository in a terminal window** and +install Git LFS in your repo. If you're sure that LFS is already installed, +you can skip this step. If you're unsure, re-installing it won't do any harm: + +```shell +git lfs install +``` + +Check this document to learn more about [using Git LFS](../../topics/git/lfs/index.md#using-git-lfs). + +### Configure Exclusive File Locks -To lock an entire directory, look for the "Lock" link next to "History". +You need [Maintainer permissions](../permissions.md) to configure +Exclusive File Locks for your project through the command line. -After you lock a file or directory, it will appear as locked in the repository -view. +The first thing to do before using File Locking is to tell Git LFS which +kind of files are lockable. The following command will store PNG files +in LFS and flag them as lockable: - +```shell +git lfs track "*.png" --lockable +``` -Once locked, any merge request to the default branch will fail -to merge until the file becomes unlocked. +After executing the above command a file named `.gitattributes` will be +created or updated with the following content: -## Unlocking a file or a directory +```shell +*.png filter=lfs diff=lfs merge=lfs -text lockable +``` -To unlock a file or a directory, follow the same procedure as when you locked -them. For a detailed view of every existing lock, see the next section on -"Viewing and managing existing locks". +You can also register a file type as lockable without using LFS (to be able, for example, +to lock/unlock a file you need in a remote server that +implements the LFS File Locking API). To do that you can edit the +`.gitattributes` file manually: -You can unlock a file that yourself or someone else previously locked as long -as you have Maintainer or above [permissions](../permissions.md) to the project. +```shell +*.pdf lockable +``` -## Viewing and managing existing locks +The `.gitattributes` file is key to the process and **must** +be pushed to the remote repository for the changes to take effect. -To view or manage every existing lock, navigate to the -**Project > Repository > Locked Files** area. There, you can view all existing -locks and [remove the ones you have permission for](#permissions-on-file-locking). +After a file type has been registered as lockable, Git LFS will make +them read-only on the file system automatically. This means you will +need to **lock the file** before [editing it](#edit-lockable-files). -## Permissions on file locking +### Lock files -The user that locks a file or directory **is the only one** that can edit and -push their changes back to the repository where the locked objects are located. +By locking a file, you verify that no one else is editing it, and +prevent anyone else from editing the file until you’re done. On the other +hand, when you unlock a file, you communicate that you've finished editing +and allow other people to edit it. -Locks can be created by any person who has [push access](../permissions.md) to the repository; i.e., -Developer and higher level, and can be removed solely by their author and any -user with Maintainer permissions and above. +To lock or unlock a file with Exclusive File Locking, open a terminal window +in your repository directory and run the commands as described below. -If a file is locked and you are not the author of its locked state, a -pre-receive hook will reject your changes when you try to push. In the -following example, a user who has no permissions on the locked `.gitignore` -file will see the message below: +To **lock** a file: ```shell -Counting objects: 3, done. -Delta compression using up to 4 threads. -Compressing objects: 100% (3/3), done. -Writing objects: 100% (3/3), 320 bytes | 0 bytes/s, done. -Total 3 (delta 1), reused 0 (delta 0) -remote: GitLab: The path '.gitignore' is locked by Administrator -To https://example.com/gitlab-org/gitlab-foss.git - ! [remote rejected] master -> master (pre-receive hook declined) - error: failed to push some refs to 'https://example.com/gitlab-org/gitlab-foss.git' +git lfs lock path/to/file.png ``` -Similarly, when a user that is not the author of the locked state of a file -accepts a merge request, an error message will appear stating that the file -is locked. +To **unlock** a file: + +```shell +git lfs unlock path/to/file.png +``` + +You can also unlock by file ID (given by LFS when you [view locked files](#view-exclusively-locked-files)): + +```shell +git lfs unlock --id=123 +``` + +If for some reason you need to unlock a file that was not locked by +yourself, you can use the `--force` flag as long as you have **Maintainer** +permissions to the project: + +```shell +git lfs unlock --id=123 --force +``` + +You can normally push files to GitLab whether they're locked or unlocked. + +NOTE: **Note:** +Although multi-branch file locks can be created and managed through the Git LFS +command line interface, file locks can be created for any file. + +### View exclusively-locked files + +To list all the files locked with LFS locally, open a terminal window in your +repo and run: + +```shell +git lfs locks +``` + +The output lists the locked files followed by the user who locked each of them +and the files' IDs. + +On the repository file tree, GitLab will display an LFS badge for files +tracked by Git LFS plus a padlock icon on exclusively-locked files: + + + +You can also [view and remove existing locks](#view-and-remove-existing-locks) from the GitLab UI. + +NOTE: **Note:** +When you rename an exclusively-locked file, the lock is lost. You'll have to +lock it again to keep it locked. + +### Edit lockable files + +Once the file is [configured as lockable](#configure-exclusive-file-locks), it is set to read-only. +Therefore, you need to lock it before editing it. + +Suggested workflow for shared projects: + +1. Lock the file. +1. Edit the file. +1. Commit your changes. +1. Push to the repo. +1. Get your changes reviewed, approved, and merged. +1. Unlock the file. + +## Default branch file and directory locks **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in GitLab Enterprise Edition 8.9. Available in [GitLab Premium](https://about.gitlab.com/pricing/). + +This process allows you to lock one file at a time through the GitLab UI and +requires access to [GitLab Premium, GitLab.com Silver](https://about.gitlab.com/pricing/), or higher tiers. + +Default branch file and directory locks only apply to the default branch set in +the project's settings (usually `master`). + +Changes to locked files on the default branch will be blocked, including merge +requests that modify locked files. Unlock the file to allow changes. + +### Lock a file or a directory + +To lock a file: + +1. Open the file or directory in GitLab. +1. Click the **Lock** button, located near the Web IDE button. + +  + +An **Unlock** button will be displayed if the file is already locked, and +will be disabled if you do not have permission to unlock the file. + +If you did not lock the file, hovering your cursor over the button will show +who locked the file. + +### View and remove existing locks + +The **Locked Files**, accessed from **Project > Repository** left menu, lists +all file and directory locks. Locks can be removed by their author, or any user +with Maintainer permissions and above. - +This list shows all the files locked either through LFS or GitLab UI. diff --git a/doc/user/project/img/code_intelligence_v13_1.png b/doc/user/project/img/code_intelligence_v13_1.png Binary files differdeleted file mode 100644 index 744195caed2..00000000000 --- a/doc/user/project/img/code_intelligence_v13_1.png +++ /dev/null diff --git a/doc/user/project/img/code_intelligence_v13_4.png b/doc/user/project/img/code_intelligence_v13_4.png Binary files differnew file mode 100644 index 00000000000..bbb6ce67bcc --- /dev/null +++ b/doc/user/project/img/code_intelligence_v13_4.png diff --git a/doc/user/project/img/code_owners_invite_members_v13_4.png b/doc/user/project/img/code_owners_invite_members_v13_4.png Binary files differnew file mode 100644 index 00000000000..852a5f68b36 --- /dev/null +++ b/doc/user/project/img/code_owners_invite_members_v13_4.png diff --git a/doc/user/project/img/code_owners_members_v13_4.png b/doc/user/project/img/code_owners_members_v13_4.png Binary files differnew file mode 100644 index 00000000000..e37fe72cd6e --- /dev/null +++ b/doc/user/project/img/code_owners_members_v13_4.png diff --git a/doc/user/project/img/file_lock_merge_request_error_message.png b/doc/user/project/img/file_lock_merge_request_error_message.png Binary files differdeleted file mode 100644 index 64bcc86ac0d..00000000000 --- a/doc/user/project/img/file_lock_merge_request_error_message.png +++ /dev/null diff --git a/doc/user/project/img/file_lock_repository_view.png b/doc/user/project/img/file_lock_repository_view.png Binary files differdeleted file mode 100644 index ced14198da9..00000000000 --- a/doc/user/project/img/file_lock_repository_view.png +++ /dev/null diff --git a/doc/user/project/img/lfs_locked_files_v13_2.png b/doc/user/project/img/lfs_locked_files_v13_2.png Binary files differnew file mode 100644 index 00000000000..0c31ce979de --- /dev/null +++ b/doc/user/project/img/lfs_locked_files_v13_2.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 56266718d12..89130d5822f 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -76,3 +76,6 @@ If you've accidentally started the import process with the wrong account, follow 1. Revoke GitLab access to your Bitbucket account, essentially reversing the process in the following procedure: [Import your Bitbucket repositories](#import-your-bitbucket-repositories). 1. Sign out of the Bitbucket account. Follow the procedure linked from the previous step. + +NOTE: **Note:** +To import a repository including LFS objects from a Bitbucket server repository, use the [Repo by URL](../import/repo_by_url.md) importer. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index f0e730564d8..d0499730bfe 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -37,7 +37,12 @@ Import your projects from Bitbucket Server to GitLab with minimal effort. empty changes. 1. Attachments in Markdown are currently not imported. 1. Task lists are not imported. -1. Emoji reactions are not imported +1. Emoji reactions are not imported. +1. [LFS objects](../../../topics/git/lfs/index.md) are not imported. + + NOTE: **Note:** + To import a repository including LFS objects from a Bitbucket server repository, use the [Repo by URL](../import/repo_by_url.md) importer. + 1. Project filtering does not support fuzzy search (only `starts with` or `full match strings` are currently supported) @@ -62,6 +67,25 @@ 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. +#### User assignment by username + +Alternatively, user assignment by username is available behind a `bitbucket_server_user_mapping_by_username` feature flag. +The importer will try to find a user in the GitLab user database using author's `username` or `slug` or `displayName`. +Falls back to author's `email` if user is not found by username. +Similarly to user assignment by email, if no such user is available, the project creator is set as the author. + +To enable or disable user assignment by username: + +Start a [Rails console](../../../administration/troubleshooting/debug.md#starting-a-rails-console-session). + +```ruby +# Enable +Feature.enable(:bitbucket_server_user_mapping_by_username) + +# Disable +Feature.disable(:bitbucket_server_user_mapping_by_username) +``` + ## Importing your Bitbucket repositories 1. Sign in to GitLab and go to your dashboard. @@ -83,4 +107,9 @@ namespace that started the import process. ## Troubleshooting +If the GUI-based import tool does not work, you can try to: + +- Use the [GitLab Import API](../../../api/import.md#import-repository-from-bitbucket-server) Bitbucket server endpoint. +- Set up [Repository Mirroring](../repository/repository_mirroring.md), which provides verbose error output. + See the [troubleshooting](bitbucket.md#troubleshooting) section for [Bitbucket](bitbucket.md). diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index d2e79458526..2957b33c20e 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -25,10 +25,10 @@ The following list illustrates the main differences between CVS and Git: are not atomic. If an operation on the repository is interrupted in the middle, the repository can be left in an inconsistent state. - **Storage method.** Changes in CVS are per file (changeset), while in Git - a committed file(s) is stored in its entirety (snapshot). That means that's + a committed file(s) is stored in its entirety (snapshot). That means it's very easy in Git to revert or undo a whole change. - **Revision IDs.** The fact that in CVS changes are per files, the revision ID - is depicted by version numbers, for example `1.4` reflects how many time a + is depicted by version numbers, for example `1.4` reflects how many times a given file has been changed. In Git, each version of a project as a whole (each commit) has its unique name given by SHA-1. - **Merge tracking.** Git uses a commit-before-merge approach rather than @@ -54,7 +54,7 @@ Wikipedia article on [comparing the different version control software](https:// CVS is old with no new release since 2008. Git provides more tools to work with (`git bisect` for one) which makes for a more productive workflow. -Migrating to Git/GitLab there is: +Migrating to Git/GitLab will benefit you: - **Shorter learning curve**, Git has a big community and a vast number of tutorials to get you started (see our [Git topic](../../../topics/git/index.md)). diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index 3838289aec4..f21ec26bdef 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -83,7 +83,7 @@ back to both GitLab and GitHub when completed.  - Your project is now mirrored on GitLab, where the Runners will be able to access + Your project is now mirrored on GitLab, where the runners will be able to access your source code and run your tests. Optional step: If you set this up on GitLab.com, make sure the project is @@ -105,7 +105,7 @@ back to both GitLab and GitHub when completed. 1. The result of the job will be visible directly from the pipeline view: -  +  NOTE: **Note:** If you don't commit very often to your project, you may want to use diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 531b308111a..4cd0c9e02c7 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -12,18 +12,6 @@ your self-managed GitLab instance. ## Overview -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](../../../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 -(such as issues and pull requests) with matching GitLab users. -If you are an administrator of a self-managed GitLab instance, you can also use the -[GitHub Rake task](../../../administration/raketasks/github_import.md) to import projects from -GitHub without the constraints of a Sidekiq worker. - The following aspects of a project are imported: - Repository description (GitLab.com & 7.7+) @@ -36,12 +24,37 @@ The following aspects of a project are imported: - Release note descriptions (GitLab.com & 8.12+) - Pull request review comments (GitLab.com & 10.2+) - Regular issue and pull request comments +- [Git Large File Storage (LFS) Objects](../../../topics/git/lfs/index.md) References to pull requests and issues are preserved (GitLab.com & 8.7+), and each imported repository maintains visibility level unless that [visibility level is restricted](../../../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects), in which case it defaults to the default project visibility. +The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or `gitlab.com/customer-success`. You can do some bulk actions to move projects to different namespaces in the rails console. + +This process does not migrate or import any types of groups or organizations from GitHub to GitLab. + +### If you're using GitLab.com + +If you're using GitLab.com, you can alternatively import +GitHub repositories using a [personal access token](#using-a-github-token), +but we don't recommend this method because it can't associate all user activity +(such as issues and pull requests) with matching GitLab users. + +### If you're importing from GitLab Enterprise + +If you're importing from GitHub Enterprise, you must enable [GitHub integration][gh-import]. + +### If you're using a self-managed GitLab instance + +If you're an administrator of a self-managed GitLab instance, you must enable +[GitHub integration][gh-import]. + +If you're an administrator of a self-managed GitLab instance, you can also use the +[GitHub Rake task](../../../administration/raketasks/github_import.md) to import projects from +GitHub without the constraints of a Sidekiq worker. + ## How it works When issues and pull requests are being imported, the importer attempts to find their GitHub authors and @@ -135,8 +148,8 @@ your GitHub repositories are listed. ## Mirroring and pipeline status sharing -Depending your GitLab tier, [project mirroring](../repository/repository_mirroring.md) can be set up to keep -your imported project in sync with its GitHub copy. +Depending on your GitLab tier, [repository mirroring](../repository/repository_mirroring.md) can be set up to keep +your imported repository in sync with its GitHub copy. Additionally, you can configure GitLab to send pipeline status updates back GitHub with the [GitHub Project Integration](../integrations/github.md). **(PREMIUM)** diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 4e5b924a1b7..c79f2be1d3f 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -37,6 +37,8 @@ When you create a project in GitLab, you'll have access to a large number of - [Signing commits](gpg_signed_commits/index.md): use GPG to sign your commits - [Deploy tokens](deploy_tokens/index.md): Manage project-based deploy tokens that allow permanent access to the repository and Container Registry. - [Web IDE](web_ide/index.md) +- [CVE ID Requests](../application_security/cve_id_request.md): Request a CVE identifier to track a + vulnerability in your project. **Issues and merge requests:** @@ -192,12 +194,16 @@ To delete a project, first navigate to the home page for that project. ### Delayed deletion **(PREMIUM)** -By default, clicking to delete a project is followed by a seven day delay. Admins can restore the project during this period of time. -This delay [may be changed by an admin](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay-premium-only). +By default, projects in a personal namespace are deleted after a seven day delay. + +Admins can restore the project during this period of time. +This delay [may be changed by an admin](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). Admins can view all projects pending deletion. If you're an administrator, go to the top navigation bar, click **Projects > Your projects**, and then select the **Deleted projects** tab. From this tab an admin can restore any project. +For information on delay deletion of projects within a group, please see [Enabling delayed Project removal](../group/index.md#enabling-delayed-project-removal) + ## CI/CD for external repositories **(PREMIUM)** Instead of importing a repository directly to GitLab, you can connect your repository @@ -318,7 +324,7 @@ through Git. For example: ```plaintext -machine example.gitlab.com +machine gitlab.example.com login <gitlab_user_name> password <personal_access_token> ``` diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md new file mode 100644 index 00000000000..be89323a246 --- /dev/null +++ b/doc/user/project/integrations/ewm.md @@ -0,0 +1,30 @@ +# IBM Engineering Workflow Management (EWM) Integration **(CORE)** + +This service allows you to navigate from GitLab to EWM work items mentioned in merge request descriptions and commit messages. Each work item reference is automatically converted to a link back to the work item. + +NOTE: **Note:** +This IBM product was [formerly named Rational Team Concert](https://jazz.net/blog/index.php/2019/04/23/renaming-the-ibm-continuous-engineering-portfolio/)(RTC). This integration is also compatible with all versions of RTC and EWM. + +1. From a GitLab project, navigate to **Settings > Integrations**, and then click **EWM**. +1. Enter the information listed below. + + | Field | Description | + | ----- | ----------- | + | `project_url` | URL of the EWM project area to link to the GitLab project. To obtain your project area URL, navigate to the path `/ccm/web/projects` and copy the listed project's URL. For example, `https://example.com/ccm/web/Example%20Project` | + | `issues_url` | URL to the work item editor in the EWM project area. The format is `<your-server-url>/resource/itemName/com.ibm.team.workitem.WorkItem/:id`. For example, `https://example.com/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/:id` | + | `new_issue_url` | URL to create a new work item in the EWM project area. Append the following fragment to your project area URL: `#action=com.ibm.team.workitem.newWorkItem`. For example, `https://example.com/ccm/web/projects/JKE%20Banking#action=com.ibm.team.workitem.newWorkItem` | + +## Reference EWM work items in commit messages + +You can use any of the keywords supported by the EWM Git Integration Toolkit to refer to work items. Work items can be referenced using the format: `<keyword> <id>`. + +You can use the following keywords: + +- `bug` +- `task` +- `defect` +- `rtcwi` +- `workitem` +- `work item` + +For more details, see the EWM documentation page [Creating links from commit comments](https://www.ibm.com/support/knowledgecenter/SSYMRC_7.0.0/com.ibm.team.connector.cq.doc/topics/t_creating_links_through_comments.html), which recommends against using the additionally-supported keyword `#` because of incompatibility with GitLab. diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md index dc6aa40ea82..0e8e082859b 100644 --- a/doc/user/project/integrations/generic_alerts.md +++ b/doc/user/project/integrations/generic_alerts.md @@ -1,124 +1,5 @@ --- -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 +redirect_to: '../../../operations/incident_management/generic_alerts.md' --- -# Generic alerts integration - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.8. - -GitLab can accept alerts from any source via a generic webhook receiver. -When you set up the generic alerts integration, a unique endpoint will -be created which can receive a payload in JSON format, and will in turn -create an issue with the payload in the body of the issue. You can always -[customize the payload](#customizing-the-payload) to your liking. - -The entire payload will be posted in the issue discussion as a comment -authored by the GitLab Alert Bot. - -NOTE: **Note:** -In GitLab versions 13.1 and greater, you can configure -[External Prometheus instances](../../../operations/metrics/alerts.md#external-prometheus-instances) -to use this endpoint. - -## Setting up generic alerts - -To obtain credentials for setting up a generic alerts integration: - -- Sign in to GitLab as a user with maintainer [permissions](../../permissions.md) for a project. -- Navigate to the **Operations** page for your project, depending on your installed version of GitLab: - - *In GitLab versions 13.1 and greater,* navigate to **Settings > Operations** in your project. - - *In GitLab versions prior to 13.1,* navigate to **Settings > Integrations** in your project. GitLab will display a banner encouraging you to enable the Alerts endpoint in **Settings > Operations** instead. -- Click **Alerts endpoint**. -- Toggle the **Active** alert setting to display the **URL** and **Authorization Key** for the webhook configuration. - -## Customizing the payload - -You can customize the payload by sending the following parameters. All fields other than `title` are optional: - -| Property | Type | Description | -| -------- | ---- | ----------- | -| `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`. | -| `fingerprint` | String or Array | The unique identifier of the alert. This can be used to group occurrences of the same alert. | - -You can also add custom fields to the alert's payload. The values of extra parameters -are not limited to primitive types, such as strings or numbers, but can be a nested -JSON object. For example: - -```json -{ "foo": { "bar": { "baz": 42 } } } -``` - -TIP: **Payload size:** -Ensure your requests are smaller than the [payload application limits](../../../administration/instance_limits.md#generic-alert-json-payloads). - -Example request: - -```shell -curl --request POST \ - --data '{"title": "Incident title"}' \ - --header "Authorization: Bearer <authorization_key>" \ - --header "Content-Type: application/json" \ - <url> -``` - -The `<authorization_key>` and `<url>` values can be found when [setting up generic alerts](#setting-up-generic-alerts). - -Example payload: - -```json -{ - "title": "Incident title", - "description": "Short description of the incident", - "start_time": "2019-09-12T06:00:55Z", - "service": "service affected", - "monitoring_tool": "value", - "hosts": "value", - "severity": "high", - "fingerprint": "d19381d4e8ebca87b55cda6e8eee7385", - "foo": { - "bar": { - "baz": 42 - } - } -} -``` - -## Triggering test alerts - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab Core in 13.2. - -After a [project maintainer or owner](#setting-up-generic-alerts) -[configures generic alerts](#setting-up-generic-alerts), you can trigger a -test alert to confirm your integration works properly. - -1. Sign in as a user with Developer or greater [permissions](../../../user/permissions.md). -1. Navigate to **Settings > Operations** in your project. -1. Click **Alerts endpoint** to expand the section. -1. Enter a sample payload in **Alert test payload** (valid JSON is required). -1. Click **Test alert payload**. - -GitLab displays an error or success message, depending on the outcome of your test. - -## Automatic grouping of identical alerts **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214557) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. - -In GitLab versions 13.2 and greater, GitLab groups alerts based on their payload. -When an incoming alert contains the same payload as another alert (excluding the -`start_time` and `hosts` attributes), GitLab groups these alerts together and -displays a counter on the -[Alert Management List](../../../operations/incident_management/incidents.md) -and details pages. - -If the existing alert is already `resolved`, then a new alert will be created instead. - - +This document was moved to [another location](../../../operations/incident_management/generic_alerts.md). diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index f2e769dcfc0..443ca11be27 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -53,7 +53,7 @@ Irker accepts channel names of the form `chan` and `#chan`, both for the case, `Aorimn` is treated as a nick and no more as a channel name. Irker can also join password-protected channels. Users need to append -`?key=thesecretpassword` to the chan name. When using this feature remember to +`?key=thesecretpassword` to the channel name. When using this feature remember to **not** put the `#` sign in front of the channel name; failing to do so will result on irker joining a channel literally named `#chan?key=password` henceforth leaking the channel key through the `/whois` IRC command (depending on IRC server diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index f11cd4d9539..3e0b6492477 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Jira integration -If you need to use Jira to track work that's implemented in GitLab, GitLab's Jira integrations make the process of working across systems more efficent. +If you need to use Jira to track work that's implemented in GitLab, GitLab's Jira integrations make the process of working across systems more efficient. This page is about the GitLab Jira integration, which is available in every GitLab project by default, allowing you to connect it to any Jira instance, whether Cloud or self-managed. To compare features with the complementary Jira Development Panel integration, see [Jira integrations](jira_integrations.md). @@ -22,7 +22,9 @@ Features include: - The Jira issue shows the activity and is closed or otherwise transitioned as specified in your GitLab settings. - **View a list of Jira issues directly in GitLab** **(PREMIUM)** -For additional features, you can install the [Jira Development Panel integration](../../../integration/jira_development_panel.md). This enables you to: +For additional features, you can install the +[Jira Development Panel integration](../../../integration/jira_development_panel.md) **(PREMIUM)**. +This enables you to: - In a Jira issue, display relevant GitLab information in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/), including related branches, commits, and merge requests. - Use Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in GitLab to add Jira comments, log time spent on the issue, or apply any issue transition. diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index 90cd9bf3acb..dd22c26be36 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -18,7 +18,7 @@ Although you can [migrate](../../../user/project/import/jira.md) your Jira issue The following Jira integrations allow different types of cross-referencing between GitLab activity and Jira issues, with additional features: - [**Jira integration**](jira.md) - This is built in to GitLab. In a given GitLab project, it can be configured to connect to any Jira instance, self-managed or Cloud. -- [**Jira development panel integration**](../../../integration/jira_development_panel.md) **(PREMIUM)** - This connects all GitLab projects under a specified group or personal namespace. +- [**Jira development panel integration**](../../../integration/jira_development_panel.md) - This connects all GitLab projects under a specified group or personal namespace. - If you're using Jira Cloud and GitLab.com, install the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-for-jira) app in the Atlassian Marketplace and see its [documentation](../../../integration/jira_development_panel.md#gitlab-for-jira-app). - For all other environments, use the [Jira DVCS Connector configuration instructions](../../../integration/jira_development_panel.md#configuration). diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index f179cd6b98e..7a1f757c138 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -39,7 +39,7 @@ Click on the service links to see further configuration instructions and details | [Emails on push](emails_on_push.md) | Email the commits and diff of each push to a list of recipients | No | | External Wiki | Replaces the link to the internal wiki with a link to an external wiki | No | | Flowdock | Flowdock is a collaboration web app for technical teams | No | -| [Generic alerts](generic_alerts.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | +| [Generic alerts](../../../operations/incident_management/generic_alerts.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | | [GitHub](github.md) **(PREMIUM)** | Sends pipeline notifications to GitHub | No | | [Hangouts Chat](hangouts_chat.md) | Receive events notifications in Google Hangouts Chat | No | | [HipChat](hipchat.md) | Private group chat and IM | No | @@ -59,6 +59,7 @@ Click on the service links to see further configuration instructions and details | [Prometheus](prometheus.md) | Monitor the performance of your deployed apps | No | | 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 | +| [EWM](ewm.md) | EWM work item 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 | @@ -82,9 +83,9 @@ Read more about [Service templates](services_templates.md). ## Project integration management -Project integraton management lets you control integration settings across all projects +Project integration management lets you control integration settings across all projects of an instance. On the project level, administrators you can choose whether to inherit the -instance configuraton or provide custom settings. +instance configuration or provide custom settings. Read more about [Project integration management](../../admin_area/settings/project_integration_management.md). diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index eda6f64ccac..0d3042463c9 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -18,6 +18,8 @@ The [Prometheus service](../prometheus.md) must be enabled. NGINX server metrics are detected, which tracks the pages and content directly served by NGINX. +[`environment_filter`](../../../../operations/metrics/dashboards/variables.md#environment_filter) is one of the predefined variables that metrics dashboards support. + | Name | Query | | ---- | ----- | | Throughput (req/sec) | `sum(rate(nginx_server_requests{server_zone!="*", server_zone!="_", %{environment_filter}}[2m])) by (code)` | diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md new file mode 100644 index 00000000000..d549921b9d9 --- /dev/null +++ b/doc/user/project/integrations/servicenow.md @@ -0,0 +1,41 @@ +--- +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# ServiceNow integration + +ServiceNow offers several integrations to help centralize and automate your +management of GitLab workflows. + +## GitLab spoke + +With the GitLab spoke in ServiceNow, you can automate actions for GitLab +projects, groups, users, issues, merge requests, branches, and repositories. + +For a full list of features, see the +[GitLab spoke documentation](https://docs.servicenow.com/bundle/orlando-servicenow-platform/page/administer/integrationhub-store-spokes/concept/gitlab-spoke.html). + +You must [configure GitLab as an OAuth2 authentication service provider](../../../integration/oauth_provider.md), +which involves creating an application and then providing the Application ID +and Secret in ServiceNow. + +## GitLab SCM and Continuous Integration for DevOps + +In ServiceNow DevOps, you can integrate with GitLab repositories and GitLab CI/CD +to centralize your view of GitLab activity and your change management processes. +You can: + +- Track information about activity in GitLab repositories and CI/CD pipelines in + ServiceNow. +- Integrate with GitLab CI/CD pipelines, by automating the creation of change + tickets and determining criteria for changes to auto-approve. + +For more information, refer to the following ServiceNow resources: + +- [ServiceNow DevOps home page](https://www.servicenow.com/products/devops.html) +- [Install DevOps](https://docs.servicenow.com/bundle/paris-devops/page/product/enterprise-dev-ops/task/activate-dev-ops.html) +- [Install DevOps Integrations](https://docs.servicenow.com/bundle/paris-devops/page/product/enterprise-dev-ops/task/activate-dev-ops-integrations.html) +- [GitLab SCM and Continuous Integration for DevOps](https://store.servicenow.com/sn_appstore_store.do#!/store/application/54dc4eacdbc2dcd02805320b7c96191e/) +- [Model a GitLab CI pipeline in DevOps](https://docs.servicenow.com/bundle/paris-devops/page/product/enterprise-dev-ops/task/model-gitlab-pipeline-dev-ops.html). diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 7be58ce4ecb..f8172a0f988 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -15,59 +15,45 @@ organize, and visualize a workflow for a feature or product release. It can be used as a [Kanban](https://en.wikipedia.org/wiki/Kanban_(development)) or a [Scrum](https://en.wikipedia.org/wiki/Scrum_(software_development)) board. -It pairs issue tracking and project management, -keeping everything in the same place, so that you don't need to jump -between different platforms to organize your workflow. +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 issue boards, you organize your issues in lists that correspond to -their assigned labels, visualizing issues designed as cards throughout those lists. +Issue boards build on the existing [issue tracking functionality](issues/index.md#issues-list) and +[labels](labels.md). Your issues appear as cards in vertical lists, organized by their assigned +labels, [milestones](#milestone-lists), or [assignees](#assignee-lists). -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. +Issue boards help you to visualize and manage your entire process in GitLab. +You add your labels, and then create the corresponding list for your existing issues. +When you're ready, you can drag your issue cards from one step to another one. - - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -Watch a [video presentation](https://youtu.be/UWsJ8tkHAa8) of -the Issue Board feature (introduced in GitLab 8.11 - August 2016). - -### 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 [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards). +An issue board can show you what issues your team is working on, who is assigned to each, +and where in the workflow those issues are. - +To let your team members organize their own workflows, use +[multiple issue boards](#use-cases-for-multiple-issue-boards). This allows creating multiple issue +boards in the same project. -## How it works + -The Issue Board feature builds on GitLab's existing -[issue tracking functionality](issues/index.md#issues-list) and -[labels](labels.md) by using them as lists of the Scrum board. +Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), +as shown in the following table: -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, so it -applies the same descriptive labels to indicate placement on the board, keeping -consistency throughout the entire development lifecycle. +| Tier | Number of project issue boards | Number of [group issue boards](#group-issue-boards) | [Configurable issue boards](#configurable-issue-boards) | [Assignee lists](#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 | -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. +To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards) below. -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. + -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, -but also allow your team members to organize their own workflow by creating -multiple issue boards within the same project. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +Watch a [video presentation](https://youtu.be/vjccjHI7aGI) of +the Issue Board feature. -## Use cases +## Issue boards use cases You can tailor GitLab issue boards to your own preferred workflow. Here are some common use cases for issue boards. @@ -138,8 +124,7 @@ 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's -list. +Create lists for each of your team members and quickly drag issues onto each team member's list. ## Issue board terminology @@ -155,8 +140,8 @@ that belong to it. Types of lists include: 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. +- [**Assignee list**](#assignee-lists): all open issues assigned to a user. +- [**Milestone list**](#milestone-lists): all open issues for a milestone. 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 @@ -172,22 +157,36 @@ card includes: 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 +## How GitLab orders issues in a list -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/). +When visiting a board, issues appear ordered in any list. You're able to change +that order by dragging the issues. The changed order is saved, so that anybody who visits the same +board later sees the reordering, with some exceptions. -### Summary of features per tier +The first time a given issue appears in any board (that is, the first time a user +loads a board containing that issue), it is ordered in relation to other issues in that list +according to [label priority](labels.md#label-priority). -Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), -as shown in the following table: +At this point, that issue is assigned a relative order value by the system, +representing its relative order with respect to the other issues in the list. Any time +you reorder that issue by dragging, its relative order value changes accordingly. -| 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 | +Also, any time that issue appears in any board when it's loaded by a user, +the updated relative order value is used for the ordering. It's only the first +time an issue appears that it takes from the priority order mentioned above. This means that +if issue `A` is reordered by dragging to be above issue `B` by any user in +a given board inside your GitLab instance, any time those two issues are subsequently +loaded in any board in the same instance (could be a different project board or a different group +board, for example), that ordering is maintained. + +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. + +## GitLab Enterprise features for issue boards + +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/). ### Multiple issue boards @@ -248,6 +247,10 @@ clicking **View scope**.  +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +Watch a [video presentation](https://youtu.be/m5UTNCSqaDk) of +the Configurable Issue Board feature. + ### Focus mode > - [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. @@ -265,7 +268,7 @@ is hidden, allowing you to focus on issues in the board. 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). +especially in combination with [assignee lists](#assignee-lists).  @@ -362,7 +365,6 @@ status. - [Create workflows](#create-workflows). - [Drag issues between lists](#drag-issues-between-lists). - [Multi-select issue cards](#multi-select-issue-cards). -- [Re-order issues in lists](#issue-ordering-in-a-list). - Drag and reorder the lists. - Change issue labels (by dragging an issue between lists). - Close an issue (by dragging it to the **Done** list). @@ -441,8 +443,9 @@ You can filter by author, assignee, milestone, and label. ### Create workflows 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 +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. @@ -456,20 +459,22 @@ A typical workflow of using an issue board would be: 1. You move issues around in lists so that your team knows who should be working on what issue. 1. When the work by one team is done, the issue can be dragged to the next list - so someone else can pick up. + so someone else can pick it up. 1. When the issue is finally resolved, the issue is moved to the **Done** list and gets automatically closed. -For instance you can create a list based on the label of 'Frontend' and one for -'Backend'. A designer can start working on an issue by adding it to the -'Frontend' list. That way, everyone knows that this issue is now being -worked on by the designers. Then, once they're done, all they have to do is -drag it over to the next list, 'Backend', where a backend developer can +For example, you can create a list based on the label of **Frontend** and one for +**Backend**. A designer can start working on an issue by adding it to the +**Frontend** list. That way, everyone knows that this issue is now being +worked on by the designers. + +Then, once they're done, all they have to do is +drag it to the next list, **Backend**, where a backend developer can eventually pick it up. Once they’re done, they move it to **Done**, to close the issue. This process can be seen clearly when visiting an issue since with every move -to another list the label changes and a system not is recorded. +to another list the label changes and a system note is recorded.  @@ -497,33 +502,6 @@ 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: @@ -537,4 +515,4 @@ A few things to remember: 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 - 20 appears. + 20 appear. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 5e456c7986c..7c9278c8403 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Knowledge +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +--- + # Design Management > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. @@ -72,39 +78,12 @@ and connect to GitLab through a personal access token. The details are explained ## The Design Management section > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223193) in GitLab 13.2, Designs are displayed directly on the issue description rather than on a separate tab. -> - The new display is deployed behind a feature flag, enabled by default. -> - It's enabled on GitLab.com. -> - It cannot be enabled or disabled per-project. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-displaying-designs-on-the-issue-description-core-only). If disabled, it will move Designs back to the **Designs** tab. +> - New display's feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/223197) in GitLab 13.4. You can find to the **Design Management** section in the issue description:  -### Enable or disable displaying Designs on the issue description **(CORE ONLY)** - -Displaying Designs on the issue description is under development but ready for -production use. It is deployed behind a feature flag that is **enabled by -default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it for your instance. - -To disable it: - -```ruby -Feature.disable(:design_management_moved) -``` - -To enable it: - -```ruby -Feature.enable(:design_management_moved) -``` - -By disabling this feature, designs will be displayed on the **Designs** tab -instead of directly on the issue description. - ## Adding designs To upload Design images, drag files from your computer and drop them in the Design Management section, @@ -252,13 +231,47 @@ Note that your resolved comment pins will disappear from the Design to free up s However, if you need to revisit or find a resolved discussion, all of your resolved threads will be available in the **Resolved Comment** area at the bottom of the right sidebar. +## Add To-Do for Designs + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198439) in GitLab 13.4. +> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-the-design-to-do-button). **(CORE ONLY)** + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +Add a to-do for a design by clicking **Add a To-Do** on the design sidebar: + + + +### Enable or disable the design To-Do button **(CORE ONLY)** + +The **Add a To-Do** button for Designs is under development but ready for production use. It is +deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:design_management_todo_button) +``` + +To disable it: + +```ruby +Feature.disable(:design_management_todo_button) +``` + ## Referring to designs in Markdown > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217160) in **GitLab 13.1**. > - It is deployed behind a feature flag, disabled by default. > - It is disabled on GitLab.com. > - It is not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-design-references-core-only). **(CORE ONLY)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-design-references). **(CORE ONLY)** We support referring to designs in [Markdown](../../markdown.md), which is available throughout the application, including in merge request and issue descriptions, in discussions and comments, and in wiki pages. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 56fb4ca5cc7..55b45bf9d3d 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -44,9 +44,9 @@ the icon and the date colored red. You can sort issues by those that are  -Due dates also appear in your [todos list](../../todos.md). +Due dates also appear in your [to-do list](../../todos.md). - + The day before an open issue is due, an email will be sent to all participants of the issue. Like the due date, the "day before the due date" is determined by the diff --git a/doc/user/project/issues/img/design_todo_button_v13_4.png b/doc/user/project/issues/img/design_todo_button_v13_4.png Binary files differnew file mode 100644 index 00000000000..62bbecf4ed9 --- /dev/null +++ b/doc/user/project/issues/img/design_todo_button_v13_4.png diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index a6911d183c1..060266a478f 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -93,7 +93,7 @@ must be set. While you can view and manage the full details of an issue on the [issue page](#issue-page), you can also work with multiple issues at a time using the [Issues List](#issues-list), -[Issue Boards](#issue-boards), Issue references, and [Epics](#epics-premium)**(PREMIUM)**. +[Issue Boards](#issue-boards), Issue references, and [Epics](#epics)**(PREMIUM)**. Key actions for Issues include: @@ -112,8 +112,6 @@ and modify them if you have the necessary [permissions](../../permissions.md). #### Real-time sidebar **(CORE ONLY)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. -> - It cannot be enabled or disabled per-project. -> - It's not recommended for production use. Assignees in the sidebar are updated in real time. This feature is **disabled by default**. To enable, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). @@ -186,8 +184,8 @@ requires [GraphQL](../../../api/graphql/index.md) to be enabled. ### Health status **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. - +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. +> - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4 and later. To help you track the status of your issues, you can assign a status to each issue to flag work that's progressing as planned or needs attention to keep on schedule: @@ -197,8 +195,11 @@ that's progressing as planned or needs attention to keep on schedule:  +After an issue is closed, its health status can't be edited and the "Edit" button becomes disabled +until the issue is reopened. + You can then see issue statuses on the -[Epic tree](../../group/epics/index.md#issue-health-status-in-epic-tree-ultimate). +[Epic tree](../../group/epics/index.md#issue-health-status-in-epic-tree). #### Disable issue health status @@ -220,4 +221,4 @@ Feature.disable(:save_issuable_health_status) - [Export issues](csv_export.md) - [Issues API](../../../api/issues.md) - Configure an [external issue tracker](../../../integration/external-issue-tracker.md) - such as Jira, Redmine, or Bugzilla. + such as Jira, Redmine, Bugzilla, or EWM. diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 77c50f9178c..5356e6aeb40 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -21,13 +21,13 @@ You can find all the information for that issue on one screen. - **1.** [New Issue, close issue (reopen issue, report issue)](#new-issue-close-issue-reopen-issue-report-issue) - **2.** [To Do](#to-do) - **3.** [Assignee](#assignee) - - **3.1.** [Multiple Assignees **(STARTER)**](#multiple-assignees-starter) -- **4.** [Epic **(PREMIUM)**](#epic-premium) + - **3.1.** [Multiple Assignees **(STARTER)**](#multiple-assignees) +- **4.** [Epic **(PREMIUM)**](#epic) - **5.** [Milestone](#milestone) - **6.** [Time tracking](#time-tracking) - **7.** [Due date](#due-date) - **8.** [Labels](#labels) -- **9.** [Weight **(STARTER)**](#weight-starter) +- **9.** [Weight **(STARTER)**](#weight) - **10.** [Confidentiality](#confidentiality) - **11.** [Lock issue](#lock-issue) - **12.** [Participants](#participants) @@ -36,7 +36,7 @@ You can find all the information for that issue on one screen. - **15.** [Edit](#edit) - **16.** [Description](#description) - **17.** [Mentions](#mentions) -- **18.** [Related Issues **(STARTER)**](#related-issues-starter) +- **18.** [Related Issues **(STARTER)**](#related-issues) - **19.** [Related Merge Requests](#related-merge-requests) - **20.** [Award emoji](#award-emoji) - **21.** [Show all activity](#show-all-activity) @@ -88,7 +88,7 @@ An issue can be assigned to: - Yourself. - Another person. -- [Many people](#multiple-assignees-starter). **(STARTER)** +- [Many people](#multiple-assignees). **(STARTER)** The assignee(s) can be changed as often as needed. The idea is that the assignees are responsible for that issue until it's reassigned to someone else to take it from there. @@ -196,7 +196,7 @@ allowing many formatting options. ### Mentions You can mention a user or a group present in your GitLab instance with `@username` or -`@groupname` and they will be notified via todos and email, unless they have disabled +`@groupname` and they will be notified via to-dos and email, unless they have disabled all notifications in their profile settings. This is controlled in the [notification settings](../../profile/notifications.md). diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 7cbd9906800..8a8359a4b02 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -11,7 +11,7 @@ etc. The available sorting options can change based on the context of the list. For sorting by issue priority, see [Label Priority](../labels.md#label-priority). In group and project issue lists, it is also possible to order issues manually, -similar to [issue boards](../issue_board.md#issue-ordering-in-a-list). +similar to [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list). ## Manual sorting @@ -31,6 +31,6 @@ a given list inside your GitLab instance, any time those two issues are subseque loaded in any list in the same instance (could be a different project issue list or a different group issue list, for example), that ordering will be maintained. -This ordering also affects [issue boards](../issue_board.md#issue-ordering-in-a-list). +This ordering also affects [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list). Changing the order in an issue list changes the ordering in an issue board, and vice versa. diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 10457e40e0b..040ca4b439b 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -37,7 +37,7 @@ Consider the following workflow: ## How browser performance testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Browser Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance-premium). +[Browser Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance). GitLab then checks this report, compares key performance metrics for each page between the source and target branches, and shows the information in the merge request. @@ -85,7 +85,7 @@ The example uses a CI/CD template that is included in all GitLab installations s or older, you must [add the configuration manually](#gitlab-versions-123-and-older) The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), -and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance-premium) +and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance) that you can later download and analyze. This implementation always takes the latest Browser Performance artifact available. If [GitLab Pages](../pages/index.md) is enabled, you can view the report directly in your browser. @@ -93,7 +93,7 @@ you can view the report directly in your browser. You can also customize the jobs with environment variables: - `SITESPEED_IMAGE`: Configure the Docker image to use for the job (default `sitespeedio/sitespeed.io`), but not the image version. -- `SITESPEED_VERSION`: Configure the version of the Docker image to use for the job (default `13.3.0`). +- `SITESPEED_VERSION`: Configure the version of the Docker image to use for the job (default `14.1.0`). - `SITESPEED_OPTIONS`: Configure any additional sitespeed.io options as required (default `nil`). Refer to the [sitespeed.io documentation](https://www.sitespeed.io/documentation/sitespeed.io/configuration/) for more details. For example, you can override the number of runs sitespeed.io @@ -196,13 +196,13 @@ performance: image: docker:git variables: URL: https://example.com - SITESPEED_VERSION: 13.3.0 + SITESPEED_VERSION: 14.1.0 SITESPEED_OPTIONS: '' services: - docker:stable-dind script: - mkdir gitlab-exporter - - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/master/index.js + - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js - mkdir sitespeed-results - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:$SITESPEED_VERSION --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL $SITESPEED_OPTIONS - mv sitespeed-results/data/performance.json performance.json @@ -226,7 +226,7 @@ performance: - docker:stable-dind script: - mkdir gitlab-exporter - - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/master/index.js + - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js - mkdir sitespeed-results - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:6.3.1 --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL - mv sitespeed-results/data/performance.json performance.json diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 3c697e22cf5..e03d4e99b86 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -23,7 +23,7 @@ Code Quality: Quality](https://gitlab.com/gitlab-org/ci-cd/codequality) project using [default Code Climate configurations](https://gitlab.com/gitlab-org/ci-cd/codequality/-/tree/master/codeclimate_defaults). - Can make use of a [template](#example-configuration). - Is available with [Auto - DevOps](../../../topics/autodevops/stages.md#auto-code-quality-starter). + DevOps](../../../topics/autodevops/stages.md#auto-code-quality). - Can be extended through [Analysis Plugins](https://docs.codeclimate.com/docs/list-of-engines) or a [custom tool](#implementing-a-custom-tool). ## Code Quality Widget @@ -69,7 +69,7 @@ For instance, consider the following workflow: This example shows how to run Code Quality on your code by using GitLab CI/CD and Docker. It requires GitLab 11.11 or later, and GitLab Runner 11.5 or later. If you are using -GitLab 11.4 or ealier, you can view the deprecated job definitions in the +GitLab 11.4 or earlier, you can view the deprecated job definitions in the [documentation archive](https://docs.gitlab.com/12.10/ee/user/project/merge_requests/code_quality.html#previous-job-definitions). First, you need GitLab Runner configured: @@ -77,7 +77,7 @@ First, you need GitLab Runner configured: - For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). - 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 Code Quality template in your CI configuration: +Once you set up GitLab Runner, include the Code Quality template in your CI configuration: ```yaml include: @@ -102,6 +102,16 @@ code_quality: CODE_QUALITY_IMAGE: "registry.example.com/codequality-fork:latest" ``` +In [GitLab 13.4 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/11100), you can override the [Code Quality environment variables](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables): + +```yaml +variables: + TIMEOUT_SECONDS: 1 + +include: + - template: Code-Quality.gitlab-ci.yml +``` + By default, report artifacts are not downloadable. If you need them downloadable on the job details page, you can add `gl-code-quality-report.json` to the artifact paths like so: @@ -126,7 +136,7 @@ This information will be automatically extracted and shown right in the merge re CAUTION: **Caution:** On self-managed instances, if a malicious actor compromises the Code Quality job -definition they will be able to execute privileged Docker commands on the Runner +definition they will be able to execute privileged Docker commands on the runner host. Having proper access control policies mitigates this attack vector by allowing access only to trusted actors. @@ -276,7 +286,7 @@ This adds SonarJava to the `plugins:` section of the [default `.codeclimate.yml` included in your project. Changes to the `plugins:` section do not affect the `exclude_patterns` section of the -defeault `.codeclimate.yml`. See the Code Climate documentation for +default `.codeclimate.yml`. See the Code Climate documentation for [excluding files and folders](https://docs.codeclimate.com/docs/excluding-files-and-folders) for more details. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index c7cabf3c73b..a0be32e0708 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -53,7 +53,7 @@ When you start a new merge request, you can immediately include the following options, or add them later by clicking the **Edit** button on the merge request's page at the top-right side: -- [Assign](#assignee) the merge request to a colleague for review. With GitLab Starter and higher tiers, you can [assign it to more than one person at a time](#multiple-assignees-starter). +- [Assign](#assignee) the merge request to a colleague for review. With GitLab Starter and higher tiers, you can [assign it to more than one person at a time](#multiple-assignees). - Set a [milestone](../milestones/index.md) to track time-sensitive changes. - Add [labels](../labels.md) to help contextualize and filter your merge requests over time. - Require [approval](merge_request_approvals.md) from your team. **(STARTER)** diff --git a/doc/user/project/merge_requests/img/browser_performance_testing.png b/doc/user/project/merge_requests/img/browser_performance_testing.png Binary files differindex 016abb89f7c..a3d7022bcfc 100644 --- a/doc/user/project/merge_requests/img/browser_performance_testing.png +++ b/doc/user/project/merge_requests/img/browser_performance_testing.png diff --git a/doc/user/project/merge_requests/img/update_approval_rule_v13_4.png b/doc/user/project/merge_requests/img/update_approval_rule_v13_4.png Binary files differnew file mode 100644 index 00000000000..af713b48140 --- /dev/null +++ b/doc/user/project/merge_requests/img/update_approval_rule_v13_4.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index a9ee9d8e507..69276f0677b 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -19,7 +19,7 @@ A. Consider you're a software developer working in a team: 1. You checkout a new branch, and submit your changes through a merge request 1. You gather feedback from your team 1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md) -1. You verify your changes with [JUnit test reports](../../../ci/junit_test_reports.md) in GitLab CI/CD +1. You verify your changes with [Unit test reports](../../../ci/unit_test_reports.md) in GitLab CI/CD 1. You avoid using dependencies whose license is not compatible with your project with [License Compliance reports](../../compliance/license_compliance/index.md) **(ULTIMATE)** 1. You request the [approval](merge_request_approvals.md) from your manager **(STARTER)** 1. Your manager: diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 97f4f202ab3..daebd71e14f 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -28,7 +28,7 @@ GET calls to a popular API endpoint in your application to see how it performs. ## How Load Performance Testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Load Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsload_performance-premium). +[Load Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsload_performance). GitLab checks this report, compares key load performance metrics between the source and target branches, and then shows the information in a merge request widget: @@ -102,7 +102,7 @@ job. An example configuration workflow: -1. Set up a GitLab Runner that can run Docker containers, such as a Runner using the +1. Set up GitLab Runner to run Docker containers, like the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). 1. Configure the default Load Performance Testing CI job in your `.gitlab-ci.yml` file. You need to include the template and configure it with variables: @@ -140,7 +140,7 @@ For example, you can override the duration of the test with a CLI option: GitLab only displays the key performance metrics in the MR widget if k6's results are saved via [summary export](https://k6.io/docs/results-visualization/json#summary-export) -as a [Load Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsload_performance-premium). +as a [Load Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsload_performance). The latest Load Performance artifact available is always used, using the summary values from the test. @@ -152,17 +152,20 @@ The CI/CD YAML configuration example above works for testing against static envi but it can be extended to work with [review apps](../../../ci/review_apps) or [dynamic environments](../../../ci/environments) with a few extra steps. -The best approach is to capture the dynamic URL into a custom environment variable that -is then [inherited](../../../ci/variables/README.md#inherit-environment-variables) -by the `load_performance` job. The k6 test script to be run should then be configured to -use that environment URL, such as: ``http.get(`${__ENV.ENVIRONMENT_URL`})``. +The best approach is to capture the dynamic URL in a [`.env` file](https://docs.docker.com/compose/env-file/) +as a job artifact to be shared, then use a custom environment variable we've provided named `K6_DOCKER_OPTIONS` +to configure the k6 Docker container to use the file. With this, k6 can then use any +environment variables from the `.env` file in scripts using standard JavaScript, +such as: ``http.get(`${__ENV.ENVIRONMENT_URL`})``. For example: 1. In the `review` job: - 1. Capture the dynamic URL and save it into a `.env` file, e.g. `echo "ENVIRONMENT_URL=$CI_ENVIRONMENT_URL" >> review.env`. - 1. Set the `.env` file to be an [`artifacts:reports:dotenv` report](../../../ci/variables/README.md#inherit-environment-variables). -1. Set the `load_performance` job to depend on the review job, so it inherits the environment variable. + 1. Capture the dynamic URL and save it into a `.env` file, e.g. `echo "ENVIRONMENT_URL=$CI_ENVIRONMENT_URL" >> review.env`. + 1. Set the `.env` file to be a [job artifact](../../../ci/pipelines/job_artifacts.md#job-artifacts). +1. In the `load_performance` job: + 1. Set it to depend on the review job, so it inherits the env file. + 1. Set the `K6_DOCKER_OPTIONS` variable with the [Docker cli option for env files](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file), for example `--env-file review.env`. 1. Configure the k6 test script to use the environment variable in it's steps. Your `.gitlab-ci.yml` file might be similar to: @@ -184,15 +187,16 @@ review: - run_deploy_script - echo "ENVIRONMENT_URL=$CI_ENVIRONMENT_URL" >> review.env artifacts: - reports: - dotenv: - review.env + paths: + - review.env rules: - if: '$CI_COMMIT_BRANCH' # Modify to match your pipeline rules, or use `only/except` if needed. load_performance: dependencies: - review + variables: + K6_DOCKER_OPTIONS: '--env-file review.env' rules: - if: '$CI_COMMIT_BRANCH' # Modify to match your pipeline rules, or use `only/except` if needed. ``` diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 407fc5db425..185ab0e6298 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -36,7 +36,7 @@ Required approvals enable multiple use cases: database, and so on, for all proposed code changes. - Designating [Code Owners as eligible approvers](#code-owners-as-eligible-approvers), determined by the files changed in a merge request. -- [Requiring approval from a security team](#security-approvals-in-merge-requests-ultimate) +- [Requiring approval from a security team](#security-approvals-in-merge-requests) before merging code that could introduce a vulnerability.**(ULTIMATE)** ### Approval Rules @@ -52,7 +52,7 @@ minimum number of required approvers can still be set in the [project settings f You can opt to define one single rule to approve a merge request among the available rules or choose more than one. Single approval rules are available in GitLab Starter and higher tiers, -while [multiple approval rules](#multiple-approval-rules-premium) are available in +while [multiple approval rules](#multiple-approval-rules) are available in [GitLab Premium](https://about.gitlab.com/pricing/) and above. NOTE: **Note:** @@ -61,6 +61,8 @@ group is public. #### Eligible Approvers +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. + The following users can approve merge requests: - Users who have been added as approvers at the project or merge request levels with @@ -84,8 +86,7 @@ if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-thei and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default) are enabled on the project settings. -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.3, -when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget, +When an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget, indicating who has engaged in the merge request review. Authors and reviewers can also easily identify who they should reach out to if they have any questions or inputs about the content of the merge request. @@ -118,7 +119,30 @@ users with Developer or higher permissions, as well as by Code Owners, indistinguishably. Alternatively, you can **require** -[Code Owner's approvals for Protected Branches](../protected_branches.md#protected-branches-approval-by-code-owners-premium). **(PREMIUM)** +[Code Owner's approvals for Protected Branches](../protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** + +#### Merge Request approval segregation of duties + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.4. + +Managers or operators with [Reporter permissions](../../permissions.md#project-members-permissions) +to a project sometimes need to be required approvers of a merge request, +before a merge to a protected branch begins. These approvers aren't allowed +to push or merge code to any branches. + +To enable this access: + +1. [Create a new group](../../group/index.md#create-a-new-group), and then + [add the user to the group](../../group/index.md#add-users-to-a-group), + ensuring you select the Reporter role for the user. +1. [Share the project with your group](../members/share_project_with_groups.md#sharing-a-project-with-a-group-of-users), + based on the Reporter role. +1. Navigate to your project's **Settings > General**, and in the + **Merge request approvals** section, click **Expand**. +1. [Add the group](../../group/index.md#create-a-new-group) to the permission list + for the protected branch. + + #### Adding / editing a default approval rule @@ -204,7 +228,7 @@ Alternatively, you can select a very specific protected branch from the **Target  -To enable this configuration, see [Code Owner’s approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners-premium). +To enable this configuration, see [Code Owner’s approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). ### Adding or removing an approval @@ -242,9 +266,9 @@ The project settings for Merge request approvals are found by going to #### Prevent overriding default approvals -By default, users are able to edit the approval rules in merge requests. If disabled, -the approval rules for all new merge requests will be determined by the -[default approval rules](#adding--editing-a-default-approval-rule). To disable this feature: +Regardless of the approval rules you choose for your project, users can edit them in every merge +request, overriding the rules you set as [default](#adding--editing-a-default-approval-rule). +To prevent that from happening: 1. Uncheck the **Can override approvers and approvals required per merge request** checkbox. 1. Click **Save changes**. @@ -267,14 +291,15 @@ from the UI. However, approvals will be reset if the target branch is changed. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. -You can allow merge request authors to self-approve merge requests. Authors -also need to be included in the approvers list in order to be able to -approve their merge request. To enable this feature: +By default, projects are configured to prevent merge requests from being approved by +their own authors. To change this setting: -1. Uncheck the **Prevent approval of merge requests by merge request author** checkbox, - which is enabled by default. +1. Go to your project's **Settings > General**, expand **Merge request approvals**. +1. Uncheck the **Prevent approval of merge requests by merge request author** checkbox. 1. Click **Save changes**. +Note that users can edit the approval rules in every merge request and override pre-defined settings unless it's set [**not to allow** overrides](#prevent-overriding-default-approvals). + #### Prevent approval of merge requests by their committers > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.10. 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 4e821145339..3a18cacde64 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 @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Reviewing and managing merge requests +# Reviewing and managing merge requests **(CORE)** Merge requests are the primary method of making changes to files in a GitLab project. Changes are proposed by [creating and submitting a merge request](creating_merge_requests.md), @@ -67,13 +67,21 @@ list.  +### Collapsed files in the Changes view + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) in GitLab 13.4. + +When you review changes in the **Changes** tab, files with a large number of changes are collapsed +to improve performance. When files are collapsed, a warning appears at the top of the changes. +Click **Expand file** on any file to view the changes for that file. + ### File-by-file diff navigation > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. > - It's deployed behind a feature flag, enabled by default. > - It's recommended for production use. > - It's enabled on GitLab.com. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-by-file-diff-navigation-core-only). +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-by-file-diff-navigation). For larger merge requests it might sometimes be useful to review single files at a time. To enable, from your avatar on the top-right navbar, click **Settings**, and go to **Preferences** on the left @@ -156,7 +164,7 @@ in a Merge Request. To do so, click the **{comment}** **comment** icon in the gu > - It's enabled on GitLab.com. > - It can be disabled or enabled per-project. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-multiline-comments-core-only). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-multiline-comments). **(CORE ONLY)** GitLab provides a way to select which lines of code a comment refers to. After starting a comment a dropdown selector is shown to select the first line that this comment refers to. @@ -203,6 +211,11 @@ If there's an [environment](../../../ci/environments/index.md) and the applicati successfully deployed to it, the deployed environment and the link to the Review App will be shown as well. +NOTE: **Note:** +When the default branch (for example, `main`) is red due to a failed CI pipeline, the `merge` button +When the pipeline fails in a merge request but it can be merged nonetheless, +the **Merge** button will be colored in red. + ### Post-merge pipeline status When a merge request is merged, you can see the post-merge pipeline status of @@ -284,15 +297,37 @@ the command line. NOTE: **Note:** This section might move in its own document in the future. -### Checkout merge requests locally +### Copy the branch name for local checkout + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23767) in GitLab 13.4. + +The merge request sidebar contains the branch reference for the source branch +used to contribute changes for this merge request. + +To copy the branch reference into your clipboard, click the **Copy branch name** button +(**{copy-to-clipboard}**) in the right sidebar. You can then use it to checkout the branch locally +via command line by running `git checkout <branch-name>`. + +### Checkout merge requests locally through the `head` ref A merge request contains all the history from a repository, plus the additional commits added to the branch associated with the merge request. Here's a few -tricks to checkout a merge request locally. +ways to checkout a merge request locally. Please note that you can checkout a merge request locally even if the source project is a fork (even a private fork) of the target project. +This relies on the merge request `head` ref (`refs/merge-requests/:iid/head`) +that is available for each merge request. It allows checking out a merge +request via its ID instead of its branch. + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223156) in GitLab +13.4, 14 days after a merge request gets closed or merged, the merge request +`head` ref will be deleted. This means that the merge request will not be available +for local checkout via the merge request `head` ref anymore. The merge request +can still be re-opened. Also, as long as the merge request's branch +exists, you can still check out the branch as it won't be affected. + #### Checkout locally by adding a Git alias Add the following alias to your `~/.gitconfig`: diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 7f752b2cc39..69a0dd6e84f 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -65,14 +65,27 @@ meaningful commit messages and: ## Enabling squash for a merge request Anyone who can create or edit a merge request can choose for it to be squashed -on the merge request form: +on the merge request form. Users can select or unselect the checkbox at the moment +they are creating the merge request:  -This can then be overridden at the time of accepting the merge request: +After the merge request is submitted, Squash and Merge can still be enabled or disabled +by editing the merge request description: + +1. Scroll to the top of the merge request page and click **Edit**. +1. Scroll down to the end of the merge request form and select the checkbox +**Squash commits when merge request is accepted**. + +This setting can then be overridden at the time of accepting the merge request. +At the end of the merge request widget, next to the **Merge** button, the **Squash commits** checkbox +can be either selected or unselected:  +Note that Squash and Merge might not be available depending on the project's configuration +for [Squash Commit Options](#squash-commits-options). + ## Commit metadata for squashed commits The squashed commit has the following metadata: @@ -97,7 +110,7 @@ squashing can itself be considered equivalent to rebasing. > - It's enabled on GitLab.com. > - It can be enabled per project. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-squash-commit-options-core-only). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-squash-commit-options). **(CORE ONLY)** With Squash Commits Options you can configure the behavior of Squash and Merge for your project. To set it up, navigate to your project's **Settings > General** and expand **Merge requests**. @@ -133,7 +146,7 @@ To enable it: # Instance-wide Feature.enable(:squash_options) # or by project -Feature.enable(:squash_options, Project.find(<project id>)) +Feature.enable(:squash_options, Project.find(<project ID>)) ``` To disable it: @@ -142,7 +155,7 @@ To disable it: # Instance-wide Feature.disable(:squash_options) # or by project -Feature.disable(:squash_options, Project.find(<project id>)) +Feature.disable(:squash_options, Project.find(<project ID>)) ``` <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 6751dde155c..56b5774f15b 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -8,9 +8,9 @@ type: reference, howto # Test Coverage Visualization **(CORE ONLY)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3708) in GitLab 12.9. -> - It's deployed behind a feature flag, disabled by default. -> - It's disabled on GitLab.com. -> - It can be enabled or disabled per-project. +> - [Feature flag enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/211410) in GitLab 13.4. +> - It's enabled on GitLab.com. +> - It can be disabled per-project. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enabling-the-feature). **(CORE ONLY)** With the help of [GitLab CI/CD](../../../ci/README.md), you can collect the test @@ -76,11 +76,9 @@ test: ## Enabling the feature -This feature comes with the `:coverage_report_view` feature flag disabled by -default. It is disabled on GitLab.com. This feature is disabled due to some performance issues with very large -data sets. When [the performance issue](https://gitlab.com/gitlab-org/gitlab/-/issues/211410) -is resolved, the feature will be enabled by default. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it for your instance. Test coverage visualization can be enabled or disabled per-project. +This feature comes with the `:coverage_report_view` feature flag enabled by +default. It is enabled on GitLab.com. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can disable it for your instance. Test coverage visualization can be enabled or disabled per-project. To enable it: diff --git a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md index e5ebc46d58f..b298c62a5e6 100644 --- a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md +++ b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md @@ -19,7 +19,7 @@ or link to useful information directly from merge requests: | [Code Quality](code_quality.md) | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | | [Display arbitrary job artifacts](../../../ci/yaml/README.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. | | [GitLab CI/CD](../../../ci/README.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. | -| [JUnit test reports](../../../ci/junit_test_reports.md) | Configure your CI jobs to use JUnit test reports, and let GitLab display a report on the merge request so that it’s easier and faster to identify the failure without having to check the entire job log. | +| [Unit test reports](../../../ci/unit_test_reports.md) | Configure your CI jobs to use Unit test reports, and let GitLab display a report on the merge request so that it’s easier and faster to identify the failure without having to check the entire job log. | | [License Compliance](../../compliance/license_compliance/index.md) **(ULTIMATE)** | Manage the licenses of your dependencies. | | [Metrics Reports](../../../ci/metrics_reports.md) **(PREMIUM)** | Display the Metrics Report on the merge request so that it's fast and easy to identify changes to important metrics. | | [Multi-Project pipelines](../../../ci/multi_project_pipelines.md) **(PREMIUM)** | When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies. | diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index aea5eef5efc..9d02a22f91e 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -117,9 +117,9 @@ From the project issue/merge request list pages and the group issue/merge reques ### Filtering in issue boards - From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [search and filter bar](../../search/index.md#issue-boards). -- From [group issue boards](../issue_board.md#group-issue-boards-premium), you can filter by only group milestones in the [search and filter bar](../../search/index.md#issue-boards). **(PREMIUM)** -- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards-starter). **(STARTER)** -- From [group issue boards](../issue_board.md#group-issue-boards-premium) you can filter by only group milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards-starter). **(STARTER)** +- From [group issue boards](../issue_board.md#group-issue-boards), you can filter by only group milestones in the [search and filter bar](../../search/index.md#issue-boards). **(PREMIUM)** +- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards). **(STARTER)** +- From [group issue boards](../issue_board.md#group-issue-boards) you can filter by only group milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards). **(STARTER)** ### Special milestone filters @@ -154,9 +154,9 @@ For project milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a  -### Group Burndown Charts **(PREMIUM)** +### Group Burndown Charts **(STARTER)** -For group milestones in [GitLab Premium](https://about.gitlab.com/pricing/), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone. +For group milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone. ### Milestone sidebar diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index cfcbf11a407..c3825371030 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -54,7 +54,7 @@ It is important to note that we have a few types of users: Administrator will have to be a member of it in order to have access to it via another project's job. -- **External users**: CI jobs created by [external users](../permissions.md#external-users-core-only) will have +- **External users**: CI jobs created by [external users](../permissions.md#external-users) will have access only to projects to which the user has at least Reporter access. This rules out accessing all internal projects by default. @@ -65,7 +65,7 @@ Let's consider the following scenario: hosted in private repositories and you have multiple CI jobs that make use of these repositories. -1. You invite a new [external user](../permissions.md#external-users-core-only). CI jobs created by that user do not +1. You invite a new [external user](../permissions.md#external-users). CI jobs created by that user do not have access to internal repositories, because the user also doesn't have the access from within GitLab. You as an employee have to grant explicit access for this user. This allows us to prevent from accidental data leakage. @@ -83,9 +83,9 @@ We try to make sure that this token doesn't leak by: 1. Masking the job token from job logs. 1. Granting permissions to the job token **only** when the job is running. -However, this brings a question about the Runners security. To make sure that +However, this brings up a question about the runner's security. To make sure that this token doesn't leak, you should also make sure that you configure -your Runners in the most possible secure way, by avoiding the following: +your runners in the most possible secure way, by avoiding the following: 1. Any usage of Docker's `privileged` mode is risky if the machines are re-used. 1. Using the `shell` executor since jobs run on the same machine. @@ -95,13 +95,13 @@ to steal the tokens of other jobs. ## Before GitLab 8.12 -In versions before GitLab 8.12, all CI jobs would use the CI Runner's token +In versions before GitLab 8.12, all CI jobs would use the runner's token to checkout project sources. -The project's Runner's token was a token that you could find under the +The project's runner token was a token that you could find under the project's **Settings > Pipelines** and was limited to access only that project. -It could be used for registering new specific Runners assigned to the project +It could be used for registering new specific runners assigned to the project and to checkout project sources. It could also be used with the GitLab Container Registry for that project, allowing pulling and pushing Docker images from within the CI job. @@ -123,7 +123,7 @@ Using single token had multiple security implications: - The token would be readable to anyone who had Developer access to a project that could run CI jobs, allowing the developer to register any specific - Runner for that project. + runner for that project. - The token would allow to access only the project's sources, forbidding from accessing any other projects. - The token was not expiring and was multi-purpose: used for checking out sources, @@ -205,7 +205,7 @@ Container Registries for private projects. > > - GitLab Runner versions prior to 1.8 don't incorporate the introduced changes > for permissions. This makes the `image:` directive not work with private -> projects automatically and it needs to be configured manually on Runner's host +> projects automatically and it needs to be configured manually on the GitLab Runner host > with a predefined account (for example administrator's personal account with > access token created explicitly for this purpose). This issue is resolved with > latest changes in GitLab Runner 1.8 which receives GitLab credentials with diff --git a/doc/user/project/operations/img/alert_list_v13_1.png b/doc/user/project/operations/img/alert_list_v13_1.png Binary files differdeleted file mode 100644 index 7a1a5f5191e..00000000000 --- a/doc/user/project/operations/img/alert_list_v13_1.png +++ /dev/null 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 e6912259bfa..badafa478ef 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 @@ -1,6 +1,4 @@ --- -last_updated: 2020-07-25 -type: reference, howto disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html' stage: Release group: Release Management diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index cabaf734d77..a7eb4c4019f 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -1,6 +1,4 @@ --- -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 @@ -9,8 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Create a GitLab Pages website from scratch This tutorial shows you how to create a Pages site from scratch. You will start with -a blank project and create your own CI file, which gives instruction to the -[GitLab Runner](https://docs.gitlab.com/runner/). When your CI/CD +a blank project and create your own CI file, which gives instruction to +a [runner](https://docs.gitlab.com/runner/). When your CI/CD [pipeline](../../../../ci/pipelines/index.md) runs, the Pages site is created. This example uses the [Jekyll](https://jekyllrb.com/) Static Site Generator (SSG). @@ -50,7 +48,7 @@ Create three files in the root (top-level) directory. ## Choose a Docker image -In this example, the Runner uses a [Docker image](../../../../ci/docker/using_docker_images.md) +In this example, the runner uses a [Docker image](../../../../ci/docker/using_docker_images.md) to run scripts and deploy the site. This specific Ruby image is maintained on [DockerHub](https://hub.docker.com/_/ruby). @@ -95,7 +93,7 @@ job: ``` For GitLab Pages, this `job` has a specific name, called `pages`. -This setting tells the Runner you want the job to deploy your website +This setting tells the runner you want the job to deploy your website with GitLab Pages: ```yaml @@ -124,7 +122,7 @@ pages: ## Specify the `public` directory for artifacts Now that Jekyll has output the files to the `public` directory, -the Runner needs to know where to get them. The artifacts are stored +the runner needs to know where to get them. The artifacts are stored in the `public` directory: ```yaml @@ -190,7 +188,7 @@ pages: - public ``` -Then configure the pipeline to run the job for the master branch only. +Then configure the pipeline to run the job for the `master` branch only. ```yaml image: ruby:2.7 diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 949a6c16c1b..9272b1f9093 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,6 +1,4 @@ --- -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 diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index eff80a4c9bd..6c3b911d033 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -59,6 +59,7 @@ To update a GitLab Pages website: | [Explore GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI/CD configuration options, Access Control, custom 404 pages, limitations, FAQ. | | [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) | Custom domains and subdomains, DNS records, and SSL/TLS certificates. | | [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates, which are automatically obtained and renewed by GitLab. | +| [Redirects](redirects.md) | Set up HTTP redirects to forward one page to another. | Learn more and see examples: diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index a6923779f24..cea6bab1a50 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,6 +1,4 @@ --- -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 @@ -36,7 +34,7 @@ If you are using [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlabcom) to hos - The domain name for GitLab Pages on GitLab.com is `gitlab.io`. - Custom domains and TLS support are enabled. - Shared runners are enabled by default, provided for free and can be used to - build your website. If you want you can still bring your own Runner. + build your website. If you want you can still bring your own runner. ## Example projects @@ -62,13 +60,8 @@ If the case of `404.html`, there are different scenarios. For example: ## Redirects in GitLab Pages -Since you cannot use any custom server configuration files, like `.htaccess` or -any `.conf` file, if you want to redirect a page to another -location, you can use the [HTTP meta refresh tag](https://en.wikipedia.org/wiki/Meta_refresh). - -Some static site generators provide plugins for that functionality so that you -don't have to create and edit HTML files manually. For example, Jekyll has the -[redirect-from plugin](https://github.com/jekyll/jekyll-redirect-from). +You can configure redirects for your site using a `_redirects` file. To learn more, read +the [redirects documentation](redirects.md). ## GitLab Pages Access Control **(CORE)** diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index d86704eb703..708d886b352 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -1,7 +1,5 @@ --- description: "How to secure GitLab Pages websites with Let's Encrypt (manual process, deprecated)." -type: howto -last_updated: 2019-07-15 --- # Let's Encrypt for GitLab Pages (manual process, deprecated) diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 6fcad0a5357..b6b881b961e 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -10,7 +10,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33422) in GitLab 11.5. > - Available on GitLab.com in GitLab 12.4. -You can enable Pages access control on your project, so that only +You can enable Pages access control on your project +if your administrator has [enabled the access control feature](../../../administration/pages/index.md#access-control) +on your GitLab instance. When enabled, only [members of your project](../../permissions.md#project-members-permissions) (at least Guest) can access your website: diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md new file mode 100644 index 00000000000..ae7b1b4fa6e --- /dev/null +++ b/doc/user/project/pages/redirects.md @@ -0,0 +1,130 @@ +--- +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 +--- + +# Create redirects for GitLab Pages + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4. +> - It's [deployed behind a feature flag](#enable-or-disable-redirects), disabled by default. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-redirects). + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +In GitLab Pages, you can [enable](#enable-or-disable-redirects) the redirects feature to configure rules to forward one URL to another using HTTP redirects. GitLab Pages uses +[Netlify style redirects](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file). + +## Supported features + +GitLab Pages only supports the +[`_redirects` plain text file syntax](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file), +and `.toml` files are not supported. + +Redirects are only supported at a basic level, and GitLab Pages doesn't support all +[special options offered by Netlify](https://docs.netlify.com/routing/redirects/redirect-options/): + +| Feature | Supported | Example | +| ------- | --------- | ------- | +| Redirects (`301`, `302`) | **{check-circle}** Yes | `/wardrobe.html /narnia.html 302` +| Rewrites (other status codes) | **{dotted-circle}** No | `/en/* /en/404.html 404` | +| [Splats](https://docs.netlify.com/routing/redirects/redirect-options/#splats) | **{dotted-circle}** No | `/news/* /blog/:splat` | +| Placeholders | **{dotted-circle}** No | `/news/:year/:month/:date/:slug /blog/:year/:month/:date/:slug` | +| Query parameters | **{dotted-circle}** No | `/store id=:id /blog/:id 301` | +| Force ([shadowing](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing)) | **{dotted-circle}** No | `/app/ /app/index.html 200!` | +| Domain-level redirects | **{dotted-circle}** No | `http://blog.example.com/* https://www.example.com/blog/:splat 301` | +| Redirect by country or language | **{dotted-circle}** No | `/ /anz 302 Country=au,nz` | +| Redirect by role | **{dotted-circle}** No | `/admin/* 200! Role=admin` | + +NOTE: **Note:** +Supported paths must start with a forward slash `/`. + +## Create redirects + +To create redirects after [enabling](#enable-or-disable-redirects) the feature, +create a configuration file named `_redirects` in the `public/` directory of your +GitLab Pages site. + +If your GitLab Pages site uses the default domain name (such as +`namespace.gitlab.io/projectname`) you must prefix every rule with the project name: + +```plaintext +/projectname/redirect-portal.html /projectname/magic-land.html 301 +/projectname/cake-portal.html /projectname/still-alive.html 302 +/projectname/wardrobe.html /projectname/narnia.html 302 +/projectname/pit.html /projectname/spikes.html 302 +``` + +If your GitLab Pages site uses [custom domains](custom_domains_ssl_tls_certification/index.md), +no project name prefix is needed. For example, if your custom domain is `example.com`, +your `_redirect` file would look like: + +```plaintext +/redirect-portal.html /magic-land.html 301 +/cake-portal.html /still-alive.html 302 +/wardrobe.html /narnia.html 302 +/pit.html /spikes.html 302 +``` + +## Files override redirects + +Files take priority over redirects. If a file exists on disk, GitLab Pages serves +the file instead of your redirect. For example, if the files `hello.html` and +`world.html` exist, and the `_redirects` file contains the following line, the redirect +is ignored because `hello.html` exists: + +```plaintext +/projectname/hello.html /projectname/world.html 302 +``` + +NOTE: **Note:** +GitLab does not support Netlify's +[force option](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing) +to change this behavior. + +## Debug redirect rules + +If a redirect isn't working as expected, or you want to check your redirect syntax, visit +`https://[namespace.gitlab.io]/projectname/_redirects`, replacing `[namespace.gitlab.io]` with +your domain name. The `_redirects` file isn't served directly, but your browser +displays a numbered list of your redirect rules, and whether the rule is valid or invalid: + +```plaintext +11 rules +rule 1: valid +rule 2: valid +rule 3: error: splats are not supported +rule 4: valid +rule 5: error: placeholders are not supported +rule 6: valid +rule 7: error: no domain-level redirects to outside sites +rule 8: error: url path must start with forward slash / +rule 9: error: no domain-level redirects to outside sites +rule 10: valid +rule 11: valid +``` + +## Enable or disable redirects + +Redirects in GitLab Pages is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. + +For [Omnibus installations](../../../administration/pages/index.md), define the +`FF_ENABLE_REDIRECTS` environment variable in the +[global settings](../../../administration/pages/index.md#global-settings). +Add the following line to `/etc/gitlab/gitlab.rb` and +[reconfigure the instance](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). + +```ruby +gitlab_pages['env']['FF_ENABLE_REDIRECTS'] = 'true' +``` + +For [source installations](../../../administration/pages/source.md), define the +`FF_ENABLE_REDIRECTS` environment variable, then +[restart GitLab](../../../administration/restart_gitlab.md#installations-from-source): + +```shell +export FF_ENABLE_REDIRECTS="true" +/path/to/pages/bin/gitlab-pages -config gitlab-pages.conf +``` diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 20880d0c4fa..6c8aacd12b3 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -100,7 +100,7 @@ To edit the details of a release: 1. Click **Save changes**. You can edit the release title, notes, associated milestones, and asset links. -To change other release information, such as the tag or release date, use the +To change the release date use the [Releases API](../../../api/releases/index.md#update-a-release). ## Add release notes to Git tags @@ -322,13 +322,14 @@ The four types of links are "Runbook," "Package," "Image," and "Other." > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. Each time a release is created, GitLab takes a snapshot of data that's related to it. -This data is saved in a JSON file and called *release evidence*. It includes linked milestones -and issues and can facilitate internal processes like external audits. +This data is saved in a JSON file and called *release evidence*. The feature currently +includes test artifacts and linked milestones (and will include issues) to facilitate +internal processes, like external audits. To access the release evidence, on the Releases page, click the link to the JSON file that's listed under the **Evidence collection** heading. -You can also [use the API](../../../api/releases/index.md#collect-release-evidence-premium-only) to +You can also [use the API](../../../api/releases/index.md#collect-release-evidence) to generate release evidence for an existing release. Because of this, each release can have multiple release evidence snapshots. You can view the release evidence and its details on the Releases page. @@ -400,7 +401,7 @@ Here is an example of a release evidence object: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. -When a release is created, release evidence is automatically collected. To initiate evidence collection any other time, use an [API call](../../../api/releases/index.md#collect-release-evidence-premium-only). You can collect release evidence multiple times for one release. +When a release is created, release evidence is automatically collected. To initiate evidence collection any other time, use an [API call](../../../api/releases/index.md#collect-release-evidence). You can collect release evidence multiple times for one release. Evidence collection snapshots are visible on the Releases page, along with the timestamp the evidence was collected. diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 54979d1c4ce..a937b6ed959 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -60,7 +60,7 @@ against accidental deletion and forced pushes. > - It's enabled on GitLab.com. > - It cannot be enabled or disabled per-project. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name-core-only). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name). **(CORE ONLY)** By default, when you create a new project in GitLab, the initial branch is called `master`. For self-managed instances, a GitLab administrator can customize the initial branch name to something diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 6636463722e..a423f58ba21 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -8,7 +8,7 @@ description: "Documentation on Git file blame." # Git file blame -> [Introduced](https://git.sphere.ly/staff/publicgitlab/commit/39c657930625ddc3ac8a921f01ffc83acadce68f) in GitLab 2.5 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/commit/39c657930625ddc3ac8a921f01ffc83acadce68f) in GitLab 2.5. [Git blame](https://git-scm.com/docs/git-blame) provides more information about every line in a file, including the last modified time, author, and diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 5526828c969..646d708d896 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -44,7 +44,7 @@ If you don't already have a GPG key, the following steps will help you get started: 1. [Install GPG](https://www.gnupg.org/download/index.html) for your operating system. - If your Operating System has `gpg2` installed, replace `gpg` with `gpg2` in + If your operating system has `gpg2` installed, replace `gpg` with `gpg2` in the following commands. 1. Generate the private/public key pair with the following command, which will spawn a series of questions: diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index a57806cf3ff..536cae263b8 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -190,7 +190,7 @@ updated every 15 minutes at most, so may not reflect recent activity. The displa The project size may differ slightly from one instance to another due to compression, housekeeping, and other factors. [Repository size limit](../../admin_area/settings/account_and_limit_settings.md) may be set by admins. -GitLab.com's repository size limit [is set by GitLab](../../gitlab_com/index.md#repository-size-limit). +GitLab.com's repository size limit [is set by GitLab](../../gitlab_com/index.md#account-and-limit-settings). ## Contributors diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 8247f69c61a..28fdda07b05 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -14,11 +14,9 @@ Git repositories become larger over time. When large files are added to a Git re - Git repository storage limits [can be reached](#storage-limits). Rewriting a repository can remove unwanted history to make the repository smaller. -[`git filter-repo`](https://github.com/newren/git-filter-repo) is a tool for quickly rewriting Git -repository history, and is recommended over both: - -- [`git filter-branch`](https://git-scm.com/docs/git-filter-branch). -- [BFG](https://rtyley.github.io/bfg-repo-cleaner/). +We **recommend [`git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/README.md)** +over [`git filter-branch`](https://git-scm.com/docs/git-filter-branch) and +[BFG](https://rtyley.github.io/bfg-repo-cleaner/). DANGER: **Danger:** Rewriting repository history is a destructive operation. Make sure to backup your repository before @@ -37,7 +35,7 @@ other internal references (refs) that are automatically created by GitLab. These - `refs/merge-requests/*` for merge requests. - `refs/pipelines/*` for - [pipelines](../../../ci/pipelines/index.md#troubleshooting-fatal-reference-is-not-a-tree). + [pipelines](../../../ci/troubleshooting.md#fatal-reference-is-not-a-tree-error). - `refs/environments/*` for environments. Git doesn't usually download these refs to make cloning and fetch faster, but we can use the `--mirror` option to @@ -49,7 +47,7 @@ download all the advertised refs. 1. Clone a fresh copy of the repository using `--bare` and `--mirror`: ```shell - git clone --bare --mirror https://example.gitlab.com/my/project.git + git clone --bare --mirror https://gitlab.example.com/my/project.git ``` 1. Using `git filter-repo`, purge any files from the history of your repository. @@ -252,9 +250,9 @@ When using repository cleanup, note: Repository size limits: -- Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md#repository-size-limit-starter-only) +- Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md#account-and-limit-settings) on self-managed instances. **(STARTER ONLY)** -- Are [set for GitLab.com](../../gitlab_com/index.md#repository-size-limit). +- Are [set for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). When a project has reached its size limit, you cannot: @@ -303,14 +301,9 @@ This process is not suitable for removing sensitive data like password or keys f Information about commits, including file content, is cached in the database, and will remain visible even after they have been removed from the repository. -<!-- ## Troubleshooting +## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +### Incorrect repository statistics shown in the GUI -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. --> +If the displayed size or commit number is different from the exported `.tar.gz` or local repository, +you can ask a GitLab administrator to [force an update](../../../administration/troubleshooting/gitlab_rails_cheat_sheet.md#incorrect-repository-statistics-shown-in-the-gui). diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index bbb673b74b0..e1d2c20850b 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -11,7 +11,8 @@ Repository mirroring allows for mirroring of repositories to and from external s used to mirror branches, tags, and commits between repositories. A repository mirror at GitLab will be updated automatically. You can also manually trigger an update -at most once every 5 minutes. +at most once every 5 minutes. Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/237891) +for discussions on how to potentially reduce the delay. ## Overview @@ -45,6 +46,11 @@ The following are some possible use cases for repository mirroring: - You have old projects in another source that you don't use actively anymore, but don't want to remove for archiving purposes. In that case, you can create a push mirror so that your active GitLab repository can push its changes to the old location. +- You are a GitLab self-managed user for privacy reasons and your instance is closed to the public, + but you still have certain software components that you want open sourced. In this case, utilizing + GitLab to be your primary repository which is closed from the public, and using push mirroring to a + GitLab.com repository that's public, allows you to open source specific projects and contribute back + to the open source community. ## Pushing to a remote repository **(CORE)** @@ -67,7 +73,7 @@ When push mirroring is enabled, only push commits directly to the mirrored repos mirror diverging. All changes will end up in the mirrored repository whenever: - Commits are pushed to GitLab. -- A [forced update](#forcing-an-update-core) is initiated. +- A [forced update](#forcing-an-update) is initiated. Changes pushed to files in the repository are automatically pushed to the remote mirror at least: @@ -247,7 +253,7 @@ directly to the repository on GitLab. Instead, any commits should be pushed to t Changes pushed to the upstream repository will be pulled into the GitLab repository, either: - Automatically within a certain period of time. -- When a [forced update](#forcing-an-update-core) is initiated. +- When a [forced update](#forcing-an-update) is initiated. CAUTION: **Caution:** If you do manually update a branch in the GitLab repository, the branch will become diverged from @@ -393,17 +399,17 @@ failed. This will become visible in either the: - Pull mirror settings page. When a project is hard failed, it will no longer get picked up for mirroring. A user can resume the -project mirroring again by [Forcing an update](#forcing-an-update-core). +project mirroring again by [Forcing an update](#forcing-an-update). ### Trigger update using API **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3453) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. Pull mirroring uses polling to detect new branches and commits added upstream, often minutes -afterwards. If you notify GitLab by [API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project-starter), +afterwards. If you notify GitLab by [API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project), updates will be pulled immediately. -For more information, see [Start the pull mirroring process for a Project](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project-starter). +For more information, see [Start the pull mirroring process for a Project](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project). ## Forcing an update **(CORE)** @@ -425,8 +431,8 @@ them and how they will be resolved. Rewriting any mirrored commit on either remote will cause conflicts and mirroring to fail. This can be prevented by: -- [Pulling only protected branches](#only-mirror-protected-branches-starter). -- [Pushing only protected branches](#push-only-protected-branches-core). +- [Pulling only protected branches](#only-mirror-protected-branches). +- [Pushing only protected branches](#push-only-protected-branches). You should [protect the branches](../protected_branches.md) you wish to mirror on both remotes to prevent conflicts caused by rewriting history. @@ -439,13 +445,13 @@ protected branches. ### Configure a webhook to trigger an immediate pull to GitLab -Assuming you have already configured the [push](#setting-up-a-push-mirror-to-another-gitlab-instance-with-2fa-activated) and [pull](#pulling-from-a-remote-repository-starter) mirrors in the upstream GitLab instance, to trigger an immediate pull as suggested above, you will need to configure a [Push Event Web Hook](../integrations/webhooks.md#push-events) in the downstream instance. +Assuming you have already configured the [push](#setting-up-a-push-mirror-to-another-gitlab-instance-with-2fa-activated) and [pull](#pulling-from-a-remote-repository) mirrors in the upstream GitLab instance, to trigger an immediate pull as suggested above, you will need to configure a [Push Event Web Hook](../integrations/webhooks.md#push-events) in the downstream instance. To do this: - Create a [personal access token](../../profile/personal_access_tokens.md) with `API` scope. - Navigate to **Settings > Webhooks** -- Add the webhook URL which in this case will use the [Pull Mirror API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project-starter) request to trigger an immediate pull after updates to the repository. +- Add the webhook URL which in this case will use the [Pull Mirror API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) request to trigger an immediate pull after updates to the repository. ```plaintext https://gitlab.example.com/api/v4/projects/:id/mirror/pull?private_token=<your_access_token> diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 452955b327c..af0daaaeca2 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -8,8 +8,8 @@ type: howto # GitLab Web Editor Sometimes it's easier to make quick changes directly from the GitLab interface -than to clone the project and use the Git command line tool. In this feature -highlight we look at how you can create a new file, directory, branch or +than to clone the project and use the Git command-line tool. In this feature +highlight, we look at how you can create a new file, directory, branch, or tag from the file browser. All of these actions are available from a single dropdown menu. @@ -17,13 +17,12 @@ dropdown menu. From a project's files page, click the '+' button to the right of the branch selector. Choose **New file** from the dropdown. -  -Enter a file name in the **File name** box. Then, add file content in the editor +Enter a file name in the **Filename** box. Then, add file content in the editor area. Add a descriptive commit message and choose a branch. The branch field will default to the branch you were viewing in the file browser. If you enter -a new branch name, a checkbox will appear allowing you to start a new merge +a new branch name, a checkbox will appear, allowing you to start a new merge request after you commit the changes. When you are satisfied with your new file, click **Commit Changes** at the bottom. @@ -32,14 +31,14 @@ When you are satisfied with your new file, click **Commit Changes** at the botto ### Template dropdowns -When starting a new project, there are some common files which the new project +When starting a new project, there are some common files that the new project might need too. Therefore a message will be displayed by GitLab to make this easy for you.  -When clicking on either `LICENSE` or `.gitignore`, etc., a dropdown will be displayed -to provide you with a template which might be suitable for your project. +When clicking on either `LICENSE` or `.gitignore` and so on, a dropdown will be displayed +to provide you with a template that might be suitable for your project.  @@ -56,16 +55,16 @@ least add a file in order for the button to show up. ## Upload a file The ability to create a file is great when the content is text. However, this -doesn't work well for binary data such as images, PDFs or other file types. In -this case you need to upload a file. +doesn't work well for binary data such as images, PDFs, or other file types. In +this case, you need to upload a file. From a project's files page, click the '+' button to the right of the branch selector. Choose **Upload file** from the dropdown.  -Once the upload dialog pops up there are two ways to upload your file. Either -drag and drop a file on the pop up or use the **click to upload** link. A file +Once the upload dialog pops up, there are two ways to upload your file. Either +drag and drop a file on the popup or use the **click to upload** link. A file preview will appear once you have selected a file to upload. Enter a commit message, choose a branch, and click **Upload file** when you are @@ -83,7 +82,7 @@ Choose **New directory** from the dropdown.  -In the new directory dialog enter a directory name, a commit message and choose +In the new directory dialog, enter a directory name, a commit message, and choose the target branch. Click **Create directory** to finish.  @@ -108,7 +107,7 @@ name or a referenced merge request or your project has an active fork relationship. If you would like to make this button appear, a possible workaround is to [remove your project's fork relationship](../settings/index.md#removing-a-fork-relationship). Once removed, the fork -relationship cannot be restored and you will no longer be able to send merge requests to the source. +relationship cannot be restored, and you will no longer be able to send merge requests to the source.  @@ -117,9 +116,9 @@ This dropdown contains the options **Create merge request and branch** and **Cre  Once you choose one of these options, a new branch or branch and merge request -will be created, based on the default -branch of your project, by default `master`. The branch name will be based on -the title of the issue and as a prefix, it will have its internal ID. Thus, the example +will be created based on the default +branch of your project (by default, `master`). The branch name will be based on +the title of the issue, and as a prefix, it will have its internal ID. Thus, the example screenshot above will create a branch named `2-make-static-site-auto-deploy-and-serve`. @@ -141,13 +140,13 @@ merge request is merged. ### Create a new branch from a project's dashboard If you want to make changes to several files before creating a new merge -request, you can create a new branch up front. From a project's files page, +request, you can create a new branch upfront. From a project's files page, choose **New branch** from the dropdown.  Enter a new **Branch name**. Optionally, change the **Create from** field -to choose which branch, tag or commit SHA this new branch will originate from. +to choose which branch, tag, or commit SHA this new branch will originate from. This field will autocomplete if you start typing an existing branch or tag. Click **Create branch** and you will be returned to the file browser on this new branch. @@ -155,7 +154,7 @@ branch.  You can now make changes to any files, as needed. When you're ready to merge -the changes back to master you can use the widget at the top of the screen. +the changes back to master, you can use the widget at the top of the screen. This widget only appears for a period of time after you create the branch or modify files. @@ -172,15 +171,15 @@ SHA. From a project's files page, choose **New tag** from the dropdown. Give the tag a name such as `v1.0.0`. Choose the branch or SHA from which you would like to create this new tag. You can optionally add a message and release notes. The release notes section supports Markdown format and you can -also upload an attachment. Click **Create tag** and you will be taken to the tag +also upload an attachment. Click **Create tag**, and you will be taken to the tag list page.  ## Tips -When creating or uploading a new file, or creating a new directory, you can -trigger a new merge request rather than committing directly to master. Enter +When creating or uploading a new file or creating a new directory, you can +trigger a new merge request rather than committing directly to `master`. Enter a new branch name in the **Target branch** field. You will notice a checkbox appear that is labeled **Start a new merge request with these changes**. After you commit the changes you will be taken to a new merge request form. diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index ae22dbc7e72..9d7d3914905 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -95,7 +95,7 @@ You can also sort the requirements list by: > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) ability to specify individual requirements and their statuses in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2. GitLab supports [requirements test -reports](../../../ci/pipelines/job_artifacts.md#artifactsreportsrequirements-ultimate) now. +reports](../../../ci/pipelines/job_artifacts.md#artifactsreportsrequirements) now. You can add a job to your CI pipeline that, when triggered, marks all existing requirements as Satisfied. diff --git a/doc/user/project/settings/img/cve_id_request_toggle.png b/doc/user/project/settings/img/cve_id_request_toggle.png Binary files differnew file mode 100644 index 00000000000..53ec804922c --- /dev/null +++ b/doc/user/project/settings/img/cve_id_request_toggle.png diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index a65e48d5d56..395d4bf30c5 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -37,6 +37,9 @@ You can select a framework label to identify that your project has certain compl - SOC 2 - Service Organization Control 2 - SOX - Sarbanes-Oxley +NOTE: **Note:** +Compliance framework labels do not affect your project settings. + ### Sharing and permissions For your repository, you can set up features such as public access, repository features, @@ -75,7 +78,7 @@ Some features depend on others: - If you disable the **Issues** option, GitLab also removes the following features: - **Issue Boards** - - [**Service Desk**](#service-desk-starter) + - [**Service Desk**](#service-desk) NOTE: **Note:** When the **Issues** option is disabled, you can still access **Milestones** @@ -97,6 +100,16 @@ Some features depend on others: - Metrics dashboard access requires reading both project environments and deployments. Users with access to the metrics dashboard can also access environments and deployments. +#### Disabling the CVE ID request button + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. + +In applicable environments, a [**Create CVE ID Request** button](../../application_security/cve_id_request.md) +is present in the issue sidebar. The button may be disabled on a per-project basis by toggling the +setting **Enable CVE ID requests in the issue sidebar**. + + + #### Disabling email notifications Project owners can disable all [email notifications](../../profile/notifications.md#gitlab-notification-emails) @@ -234,10 +247,10 @@ This action: - Deletes a project including all associated resources (issues, merge requests etc). - From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, -group admins can [configure](../../group/index.md#enabling-delayed-project-removal-premium) projects within a group +group admins can [configure](../../group/index.md#enabling-delayed-project-removal) projects within a group to be deleted after a delayed period. When enabled, actual deletion happens after number of days -specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay-premium-only). +specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). CAUTION: **Warning:** The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index cbc4895f014..57cb610a2e9 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -15,10 +15,7 @@ type: reference, howto > - It's recommended for production use. > - For GitLab self-managed instances, GitLab administrators can [disable it](#enable-or-disable-project-access-tokens). -Project access tokens are scoped to a project and can be used to authenticate with the [GitLab API](../../../api/README.md#personalproject-access-tokens). - -<!-- Commented out until https://gitlab.com/gitlab-org/gitlab/-/issues/219551 is fixed --> -<!-- You can also use project access tokens with Git to authenticate over HTTP or SSH. --> +Project access tokens are scoped to a project and can be used to authenticate with the [GitLab API](../../../api/README.md#personalproject-access-tokens). You can also use project access tokens with Git to authenticate over HTTP or SSH. Project access tokens expire on the date you define, at midnight UTC. @@ -43,7 +40,8 @@ For each project access token created, a bot user will also be created and added For the bot: - The name is set to the name of the token. -- The username is set to `project_{project_id}_bot`, such as `project_123_bot`. +- The username is set to `project_{project_id}_bot` for the first access token, such as `project_123_bot`. +- The username is set to `project_{project_id}_bot{bot_count}` for further access tokens, such as `project_123_bot1`. API calls made with a project access token are associated with the corresponding bot user. @@ -54,7 +52,8 @@ When the project access token is [revoked](#revoking-a-project-access-token) the 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). -Project bot users are a [GitLab-created service account](../../../subscriptions/index.md#self-managed) and do not count as a licensed seat. +Project bot users are a [GitLab-created service account](../../../subscriptions/self_managed/index.md#choose-the-number-of-users), but count as a licensed seat. +These users will not count against your licensed seat in the future when [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/223695) is resolved. ## Revoking a project access token diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 4e401014122..ce14cefba92 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -82,7 +82,7 @@ or [create a new project from a template](../../../gitlab-basics/create-project. 1. Visit your website and look at the bottom-left corner of the screen to see the new **Edit this page** button. Anyone satisfying the [requirements](#requirements) will be able to edit the -content of the pages without prior knowledge of Git nor of your site's +content of the pages without prior knowledge of Git or of your site's codebase. NOTE: **Note:** diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 12ba55cafdc..821b42af049 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -53,21 +53,42 @@ If you are missing Syntax Highlighting support for any language, we prepared a s NOTE: **Note:** Single file editing is based on the [Ace Editor](https://ace.c9.io). -### Schema based validation +### Themes + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in GitLab in 13.0. +> - Full Solarized Dark Theme [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219228) in GitLab 13.1. + +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) and +the [solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228), +which apply to the entire Web IDE screen. + +| Solarized Light Theme | Solarized Dark Theme | Dark Theme | +|---------------------------------------------------------------|-------------------------------------------------------------|-----------------------------------------| +|  |  |  | + +## Schema based validation -> - Support for `.gitlab-ci.yml` validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) in GitLab 13.2. +> - Support for validation based on predefined schemas [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) in GitLab 13.2. > - It was deployed behind a feature flag, disabled by default. > - It's enabled on GitLab.com. > - It cannot be enabled or disabled per-project. -> - For GitLab self-managed instances, GitLab administrators can opt to [enable it](#enable-or-disable-schema-based-validation-core-only). +> - For GitLab self-managed instances, GitLab administrators can opt to [enable it](#enable-or-disable-validation-based-on-predefined-schemas). +> - Support for validation based on custom schemas [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/226982) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. The Web IDE provides validation support for certain JSON and YAML files using schemas -based on the [JSON Schema Store](https://www.schemastore.org/json/). This feature is -only supported for the `.gitlab-ci.yml` file. +based on the [JSON Schema Store](https://www.schemastore.org/json/). -#### Enable or disable Schema based validation **(CORE ONLY)** +### Predefined schemas -Schema based validation is under development and not ready for production use. It is +The Web IDE has validation for certain files built in. This feature is only supported for +the `*.gitlab-ci.yml` files. + +#### Enable or disable validation based on predefined schemas **(CORE ONLY)** + +Validation based on predefined schemas is under development and not ready for production use. It is deployed behind a feature flag that is **disabled by default** for self-managed instances, [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can enable it for your instance. @@ -84,21 +105,35 @@ To disable it: Feature.disable(:schema_linting) ``` -### Themes +### Custom schemas **(PREMIUM)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in GitLab in 13.0. -> - Full Solarized Dark Theme [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219228) in GitLab 13.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/226982) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. -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 Web IDE also allows you to define custom schemas for certain JSON/YAML files in your project. +You can do so by defining a `schemas` entry in the `.gitlab/.gitlab-webide.yml` file inside the +repository's root. Here is an example configuration: -The themes are available only in the Web IDE file editor, except for the [dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/209808) and -the [solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228), -which apply to the entire Web IDE screen. +```yaml +schemas: + - uri: https://json.schemastore.org/package + match: + - package.json + - uri: https://somewebsite.com/first/raw/url + match: + - data/release_posts/unreleased/*.{yml,yaml} + - uri: https://somewebsite.com/second/raw/url + match: + - "*.meta.json" +``` -| Solarized Light Theme | Solarized Dark Theme | Dark Theme | -|---------------------------------------------------------------|-------------------------------------------------------------|-----------------------------------------| -|  |  |  | +Each schema entry supports two properties: + +- `uri`: please provide an absolute URL for the schema definition file here. The schema from this URL +is loaded when a matching file is open. +- `match`: a list of matching paths or glob expressions. If a schema matches a particular path pattern, +it will be applied to that file. Please enclose the pattern in quotes if it begins with an asterisk (`*`), +it's be applied to that file. If a pattern begins with an asterisk (`*`), enclose it in quotation +marks. Otherwise, the configuration file is not valid YAML. ## Configure the Web IDE @@ -236,12 +271,12 @@ below. CAUTION: **Warning:** Interactive Web Terminals for the Web IDE is currently in **Beta**. -Shared Runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab/-/issues/24674), -so you would need to use your own private Runner(s) to make use of this feature. +Shared runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab/-/issues/24674), +so you would need to use your own private runner to make use of this feature. [Interactive Web Terminals](../../../ci/interactive_web_terminal/index.md) give the project [Maintainers](../../permissions.md#project-members-permissions) -user access to a terminal to interact with the Runner directly from +user access to a terminal to interact with the runner directly from GitLab, including through the Web IDE. ### Runner configuration @@ -249,7 +284,7 @@ GitLab, including through the Web IDE. Some things need to be configured in the runner for the interactive web terminal to work: -- The Runner needs to have +- The runner needs to have [`[session_server]` configured properly](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section). This section requires at least a `session_timeout` value (which defaults to 1800 seconds) and a `listen_address` value. If `advertise_address` is not defined, `listen_address` is used. @@ -346,7 +381,7 @@ environment. NOTE: **Note:** Only file changes in the Web IDE are synced to the terminal. Changes made in the terminal are **not** synced to the Web IDE. -This feature is only available for Kubernetes Runners. +This feature is only available for Kubernetes runners. To enable file syncing to the web terminal, the `.gitlab/.gitlab-webide.yml` file needs to have a `webide-file-sync` service configured. Here is an example @@ -373,7 +408,7 @@ terminal: more information. - `$CI_PROJECT_DIR` is a [predefined environment variable](../../../ci/variables/predefined_variables.md) - for GitLab Runners. This is where your project's repository will be. + for GitLab Runner. This is where your project's repository will be. Once you have configured the web terminal for file syncing, then when the web terminal is started, a **Terminal** status will be visible in the status bar. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 5503cd97628..40ef5e216fd 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -165,7 +165,7 @@ Similar to versioned diff file views, you can see the changes made in a given Wi > - Git events were [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in **GitLab 13.0.** > - It's enabled on GitLab.com. > - Git access activity creation is managed by a feature flag. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-wiki-events-in-git-core-only). **(CORE ONLY)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-wiki-events-in-git). **(CORE ONLY)** Wiki events (creation, deletion, and updates) are tracked by GitLab and displayed on the [user profile](../../profile/index.md#user-profile), |
