diff options
Diffstat (limited to 'doc/user/project')
135 files changed, 1139 insertions, 931 deletions
diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index 8d8ff942d05..aa8c21fc781 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -15,25 +15,24 @@ Markdown fields. When you start typing a word in a Markdown field with one of the following characters, GitLab progressively autocompletes against a set of matching values. The string matching is not case sensitive. -| Character | Autocompletes | -| :-------- | :------------ | -| `~` | Labels | -| `%` | Milestones | -| `@` | Users and groups | -| `#` | Issues | -| `!` | Merge requests | -| `&` | Epics | -| `$` | Snippets | -| `:` | Emoji | -| `/` | Quick Actions | - -Up to 5 of the most relevant matches are displayed in a popup list. When you -select an item from the list, the value is entered in the field. The more -characters you enter, the more precise the matches are. +| Character | Autocompletes | Relevant matches shown | +| :-------- | :------------ | :---- | +| `~` | Labels | 20 | +| `%` | Milestones | 5 | +| `@` | Users and groups | 10 | +| `#` | Issues | 5 | +| `!` | Merge requests | 5 | +| `&` | Epics | 5 | +| `$` | Snippets | 5 | +| `:` | Emoji | 5 | +| `/` | Quick Actions | 100 | + +When you select an item from the list, the value is entered in the field. +The more characters you enter, the more precise the matches are. Autocomplete characters are useful when combined with [Quick Actions](quick_actions.md). -## Example +## User autocomplete Assume your GitLab instance includes the following users: @@ -49,17 +48,9 @@ Assume your GitLab instance includes the following users: <!-- vale gitlab.Spelling = YES --> -In an Issue comment, entering `@l` results in the following popup list -appearing. Note that user `shelba` is not included, because the list includes -only the 5 users most relevant to the Issue. - - - -If you continue to type, `@le`, the popup list changes to the following. The -popup now only includes users where `le` appears in their username, or a word in -their name. - - +User autocompletion sorts by the users whose username or name start with your query first. +For example, typing `@lea` shows `leanna` first and typing `@ros` shows `Rosemarie Rogahn` and `Rosy Grant` first. +Any usernames or names that include your query are shown afterwards in the autocomplete menu. You can also search across the full name to find a user. -To find `Rosy Grant`, even if their username is for example `hunter2`, you can type their full name without spaces like `@rosygrant`. +To find `Rosy Grant`, even if their username is for example `alessandra`, you can type their full name without spaces like `@rosygrant`. diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 7e6bba30001..783232ca7f9 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -19,7 +19,7 @@ project maintainers. ## Project badges -Badges can be added to a project by Maintainers or Owners, and will then be visible on the project's overview page. +Badges can be added to a project by Maintainers or Owners, and are visible on the project's overview page. If you find that you have to add the same badges to several projects, you may want to add them at the [group level](#group-badges). To add a new badge to a project: @@ -52,7 +52,7 @@ To add this badge to a project: ## Group badges -Badges can be added to a group and will then be visible on every project's +Badges can be added to a group and are visible on every project's overview page that's under that group. In this case, they cannot be edited or deleted on the project level. If you need to have individual badges for each project, consider adding them on the [project level](#project-badges) or use @@ -75,7 +75,7 @@ Badges directly associated with a project can be configured on the ## Placeholders The URL a badge points to, as well as the image URL, can contain placeholders -which will be evaluated when displaying the badge. The following placeholders +which are evaluated when displaying the badge. The following placeholders are available: - `%{project_path}`: Path of a project including the parent groups diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index eb6b8302667..e329ec4f903 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -140,13 +140,11 @@ To create and add a new Kubernetes cluster to your project, group, or instance: 1. Click **Review policy**. 1. Enter a suitable name for this policy, and click **Create Policy**. You can now close this window. -1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an EKS management IAM role. - To do so, follow the [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) instructions - to create a IAM role suitable for managing the AWS EKS cluster's resources on your behalf. +1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an **EKS IAM role** following the [Amazon EKS cluster IAM role instructions](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html). This role should exist so that Kubernetes clusters managed by Amazon EKS can make calls to other AWS services on your behalf to manage the resources that you use with the service. In addition to the policies that guide suggests, you must also include the `AmazonEKSClusterPolicy` policy for this role in order for GitLab to manage the EKS cluster correctly. -1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM role: - 1. From the left panel, select **Roles**. +1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create another IAM role which will be used by GitLab to authenticate with AWS. Follow these steps to create it: + 1. On the AWS IAM console, select **Roles** from the left panel. 1. Click **Create role**. 1. Under `Select type of trusted entity`, select **Another AWS account**. 1. Enter the Account ID from GitLab into the `Account ID` field. @@ -326,7 +324,7 @@ If a default Storage Class doesn't already exist and is desired, follow Amazon's to create one. Alternatively, disable PostgreSQL by setting the project variable -[`POSTGRES_ENABLED`](../../../topics/autodevops/customize.md#environment-variables) to `false`. +[`POSTGRES_ENABLED`](../../../topics/autodevops/customize.md#cicd-variables) to `false`. ### Deploy the app to EKS diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index d3d434762ab..aabda474043 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -58,7 +58,6 @@ Kubernetes version to any supported version at any time: - 1.17 (support ends on September 22, 2021) - 1.16 (support ends on July 22, 2021) - 1.15 (support ends on May 22, 2021) -- 1.14 (deprecated, support ends on December 22, 2020) Some GitLab features may support versions outside the range provided here. @@ -87,7 +86,7 @@ differentiates the new cluster from the rest. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the -[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables) work. +[environment-specific CI/CD variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables) work. The default environment scope is `*`, which means all jobs, regardless of their environment, use that cluster. Each scope can be used only by a single cluster @@ -201,7 +200,7 @@ To clear the cache: You do not need to specify a base domain on cluster settings when using GitLab Serverless. The domain in that case is specified as part of the Knative installation. See [Installing Applications](#installing-applications). -Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an environment variable. +Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an deployment variable. If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain is used for the different stages. For example, Auto Review Apps and Auto Deploy. @@ -289,7 +288,7 @@ A Kubernetes cluster can be the destination for a deployment job. If the cluster from your jobs using tools such as `kubectl` or `helm`. - You don't use the GitLab cluster integration, you can still deploy to your cluster. However, you must configure Kubernetes tools yourself - using [environment variables](../../../ci/variables/README.md#custom-cicd-variables) + using [CI/CD variables](../../../ci/variables/README.md#custom-cicd-variables) before you can interact with the cluster from your jobs. ### Deployment variables @@ -313,9 +312,9 @@ following command in your deployment job script, for Kubernetes to access the re The Kubernetes cluster integration exposes these [deployment variables](../../../ci/variables/README.md#deployment-variables) in the GitLab CI/CD build environment to deployment jobs. Deployment jobs have -[defined a target environment](../../../ci/environments/index.md#defining-environments). +[defined a target environment](../../../ci/environments/index.md). -| Variable | Description | +| Deployment Variable | Description | |----------------------------|-------------| | `KUBE_URL` | Equal to the API URL. | | `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. | @@ -346,14 +345,14 @@ You can customize the deployment namespace in a few ways: - For **non-managed** clusters, the auto-generated namespace is set in the `KUBECONFIG`, but the user is responsible for ensuring its existence. You can fully customize this value using - [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configuring-kubernetes-deployments) + [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configure-kubernetes-deployments) in `.gitlab-ci.yml`. When you customize the namespace, existing environments remain linked to their current namespaces until you [clear the cluster cache](#clearing-the-cluster-cache). WARNING: -By default, anyone who can create a deployment job can access any CI variable in +By default, anyone who can create a deployment job can access any CI/CD variable in an environment's deployment job. This includes `KUBECONFIG`, which gives access to any secret available to the associated service account in your cluster. To keep your production credentials safe, consider using @@ -407,7 +406,7 @@ deployments, replica sets, and pods are annotated with: - `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` `$CI_ENVIRONMENT_SLUG` and `$CI_PROJECT_PATH_SLUG` are the values of -the CI variables. +the CI/CD variables. You must be the project owner or have `maintainer` permissions to use terminals. Support is limited to the first container in the first pod of your environment. @@ -432,8 +431,8 @@ Reasons for failure include: - The token you gave GitLab does not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) privileges required by GitLab. -- Missing `KUBECONFIG` or `KUBE_TOKEN` variables. To be passed to your job, they must have a matching - [`environment:name`](../../../ci/environments/index.md#defining-environments). If your job has no +- Missing `KUBECONFIG` or `KUBE_TOKEN` deployment variables. To be passed to your job, they must have a matching + [`environment:name`](../../../ci/environments/index.md). If your job has no `environment:name` set, the Kubernetes credentials are not passed to it. NOTE: diff --git a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md index 0c4ec72ed5b..d64ebfd9385 100644 --- a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md @@ -15,7 +15,7 @@ applications through GMAv2 exclusively when using Container Network Security. The following steps are recommended to install and use Container Host Security through GitLab: 1. [Install at least one runner and connect it to GitLab](https://docs.gitlab.com/runner/). -1. [Create a group](../../../../group/#create-a-new-group). +1. [Create a group](../../../../group/#create-a-group). 1. [Connect a Kubernetes cluster to the group](../../add_remove_clusters.md). 1. [Create a cluster management project and associate it with the Kubernetes cluster](../../../../clusters/management_project.md). @@ -57,7 +57,7 @@ initial troubleshooting steps that resolve the most common problems: 1. If things still aren't working, a more assertive set of actions may help get things back to a good state: - - Stop and [delete the problematic environment](../../../../../ci/environments/#delete-environments-through-the-ui) + - Stop and [delete the problematic environment](../../../../../ci/environments/#delete-a-stopped-environment) in GitLab. - Delete the relevant namespace in Kubernetes by running `kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster. diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index e530f0dfcda..14db98c7ce7 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -15,7 +15,7 @@ applications through GMAv2 exclusively when using Container Network Security. The following steps are recommended to install and use Container Network Security through GitLab: 1. [Install at least one runner and connect it to GitLab](https://docs.gitlab.com/runner/). -1. [Create a group](../../../../group/#create-a-new-group). +1. [Create a group](../../../../group/#create-a-group). 1. [Connect a Kubernetes cluster to the group](../../add_remove_clusters.md). 1. [Create a cluster management project and associate it with the Kubernetes cluster](../../../../clusters/management_project.md). @@ -131,7 +131,7 @@ initial troubleshooting steps that resolve the most common problems: 1. If things still aren't working, a more assertive set of actions may help get things back into a good state: - - Stop and [delete the problematic environment](../../../../../ci/environments/index.md#delete-environments-through-the-ui) in GitLab. + - Stop and [delete the problematic environment](../../../../../ci/environments/index.md#delete-a-stopped-environment) in GitLab. - Delete the relevant namespace in Kubernetes by running `kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster. - Rerun the application project pipeline to redeploy the application. diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 192a7c7cd39..f78fb2ed1ef 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -367,12 +367,11 @@ sam init -h ### Setting up your AWS credentials with your GitLab account In order to interact with your AWS account, the GitLab CI/CD pipelines require both -`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be set in the project's CI/CD -variables. +`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be set in the project's CI/CD variables. To set these: -1. Navigate to the project's **Settings > CI / CD**. +1. Navigate to the project's **Settings > CI/CD**. 1. Expand the **Variables** section and create entries for `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. 1. Mask the credentials so they do not show in logs using the **Masked** toggle. @@ -424,8 +423,8 @@ deploys your application. If your: - Incompatible versions of software. For example, Python runtime version might be different from the Python on the build machine. Address this by installing the required versions of the software. - - You may not be able to access your AWS account from GitLab. Check the environment - variables you set up with AWS credentials. + - You may not be able to access your AWS account from GitLab. Check the CI/CD variables + you set up with AWS credentials. - You may not have permission to deploy a serverless application. Make sure you provide all required permissions to deploy a serverless application. diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index c7ed8d6d2a5..0f7f5e23e59 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -90,7 +90,7 @@ memory. **RBAC must be enabled.** NOTE: Running `kubectl` commands on your cluster requires setting up access to the cluster first. For clusters created on GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl), - for other platforms [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + for other platforms [Install kubectl](https://kubernetes.io/docs/tasks/tools/). 1. The Ingress is now available at this address and routes incoming requests to the proper service based on the DNS name in the request. To support this, a wildcard DNS record should be created for the desired domain name. For example, @@ -396,7 +396,7 @@ kubectl create secret generic my-secrets -n "$KUBE_NAMESPACE" --from-literal MY_ #### Part of deployment job -You can extend your `.gitlab-ci.yml` to create the secrets during deployment using the [environment variables](../../../../ci/variables/README.md) +You can extend your `.gitlab-ci.yml` to create the secrets during deployment using the [CI/CD variables](../../../../ci/variables/README.md) stored securely under your GitLab project. ```yaml @@ -521,7 +521,7 @@ Running `kubectl` commands on your cluster requires setting up access to the cluster first. For clusters created on: - GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl) -- Other platforms, see [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). +- Other platforms, see [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/). ### Enable request log template @@ -769,7 +769,7 @@ or with other versions of Python. Running `kubectl` commands on your cluster requires setting up access to the cluster first. For clusters created on GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl). - For other platforms, [install `kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + For other platforms, [install `kubectl`](https://kubernetes.io/docs/tasks/tools/). ```shell kubectl create --namespace istio-system secret tls istio-ingressgateway-certs \ diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index 0e8c1bf8f4d..f1071af7c1f 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -19,10 +19,13 @@ Code Intelligence is built into GitLab and powered by [LSIF](https://lsif.dev/) (Language Server Index Format), a file format for precomputed code intelligence data. +NOTE: +You can automate this feature in your applications by using [Auto DevOps](../../topics/autodevops/index.md). + ## Configuration Enable code intelligence for a project by adding a GitLab CI/CD job to the project's -`.gitlab-ci.yml` which will generate the LSIF artifact: +`.gitlab-ci.yml` which generates the LSIF artifact: ```yaml code_navigation: diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 72695580d9d..368417ac00b 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -16,6 +16,10 @@ of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the workflow they already use without any need to access Kubernetes. +NOTE: +If you have a Kubernetes cluster, you can Auto Deploy applications to production +environments by using [Auto DevOps](../../topics/autodevops/index.md). + ## Overview With Deploy Boards you can gain more insight into deploys with benefits such as: @@ -71,7 +75,7 @@ specific environment, there are a lot of use cases. To name a few: To display the Deploy Boards for a specific [environment](../../ci/environments/index.md) you should: -1. Have [defined an environment](../../ci/environments/index.md#defining-environments) with a deploy stage. +1. Have [defined an environment](../../ci/environments/index.md) with a deploy stage. 1. Have a Kubernetes cluster up and running. @@ -86,11 +90,11 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ [`kubernetes`](https://docs.gitlab.com/runner/executors/kubernetes.html) executor. 1. Configure the [Kubernetes integration](clusters/index.md) in your project for the cluster. The Kubernetes namespace is of particular note as you need it - for your deployment scripts (exposed by the `KUBE_NAMESPACE` environment variable). + for your deployment scripts (exposed by the `KUBE_NAMESPACE` deployment variable). 1. Ensure Kubernetes annotations of `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG` and `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` are applied to the deployments, replica sets, and pods, where `$CI_ENVIRONMENT_SLUG` and - `$CI_PROJECT_PATH_SLUG` are the values of the CI variables. This is so we can + `$CI_PROJECT_PATH_SLUG` are the values of the CI/CD variables. This is so we can lookup the proper environment in a cluster/namespace which may have more than one. These resources should be contained in the namespace defined in the Kubernetes service setting. You can use an [Auto deploy](../../topics/autodevops/stages.md#auto-deploy) `.gitlab-ci.yml` @@ -159,6 +163,6 @@ version of your application. ## Further reading - [GitLab Auto deploy](../../topics/autodevops/stages.md#auto-deploy) -- [GitLab CI/CD environment variables](../../ci/variables/README.md) +- [GitLab CI/CD variables](../../ci/variables/README.md) - [Environments and deployments](../../ci/environments/index.md) - [Kubernetes deploy example](https://gitlab.com/gitlab-examples/kubernetes-deploy) diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 6f05c40eefc..8606ce36a82 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -10,7 +10,7 @@ type: howto > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17894) in GitLab 10.7. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199370) from **Settings > Repository** in GitLab 12.9. > - [Added `write_registry` scope](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI / CD** in GitLab 12.10.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI/CD** in GitLab 12.10.1. > - [Added package registry scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. Deploy tokens allow you to download (`git clone`) or push and pull packages and @@ -20,7 +20,7 @@ Deploy tokens can be managed by [maintainers only](../../permissions.md). Deploy tokens cannot be used with the GitLab API. -If you have a key pair, you might want to use [deploy keys](../../../ssh/README.md#deploy-keys) +If you have a key pair, you might want to use [deploy keys](../../project/deploy_keys/index.md) instead. ## Creating a Deploy Token @@ -130,6 +130,22 @@ To pull packages in the GitLab package registry, you must: 1. For the [package type of your choice](../../packages/index.md), follow the authentication instructions for deploy tokens. +Example request publishing a generic package using a deploy token: + +```shell +curl --header "DEPLOY-TOKEN: <deploy_token>" \ + --upload-file path/to/file.txt \ + "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?status=hidden" +``` + +Example response: + +```json +{ + "message":"201 Created" +} +``` + ### Push or upload packages > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. @@ -169,7 +185,7 @@ apply consistently when cloning the repository of related projects. There's a special case when it comes to Deploy Tokens. If a user creates one named `gitlab-deploy-token`, the username and token of the Deploy Token is -automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` +automatically exposed to the CI/CD jobs as CI/CD variables: `CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD`, respectively. After you create the token, you can sign in to the Container Registry by using @@ -180,7 +196,6 @@ docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY ``` NOTE: -The special handling for the `gitlab-deploy-token` deploy token is not currently -implemented for group deploy tokens. For the deploy token to be available for -CI/CD jobs, it must be created at the project level. For details, see -[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/214014). +The special handling for the `gitlab-deploy-token` deploy token is not +implemented for group deploy tokens. To make the group-level deploy token available for +CI/CD jobs, use the workaround in [issue 214014](https://gitlab.com/gitlab-org/gitlab/-/issues/214014). diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index c56470ee07a..2267cb55f16 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -20,7 +20,7 @@ Every GitLab project can define its own set of description templates as they are added to the root directory of a GitLab project's repository. Description templates must be written in [Markdown](../markdown.md) and stored -in your project's repository under a directory named `.gitlab`. Only the +in your project's repository in the `.gitlab` directory. Only the templates of the default branch are taken into account. To learn how to create templates for various file types in groups, visit @@ -28,19 +28,23 @@ To learn how to create templates for various file types in groups, visit ## Use cases +These are some situations when you might find description templates useful: + +- You can create issues and merge request templates for different + stages of your workflow, for example, feature proposal, feature improvement, or a bug report. - Add a template to be used in every issue for a specific project, giving instructions and guidelines, requiring for information specific to that subject. For example, if you have a project for tracking new blog posts, you can require the - title, outlines, author name, author social media information, and so on. + title, outlines, author name, and author social media information. - Following the previous example, you can make a template for every MR submitted with a new blog post, requiring information about the post date, front matter data, images guidelines, link to the related issue, reviewer name, and so on. - You can also create issues and merge request templates for different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. -- You can use an [issue description template](#creating-issue-templates) as a +- You can use an [issue description template](#create-an-issue-template) as a [Service Desk email template](service_desk.md#new-service-desk-issues). -## Creating issue templates +## Create an issue template Create a new Markdown (`.md`) file inside the `.gitlab/issue_templates/` directory in your repository. Commit and push to your default branch. @@ -65,13 +69,13 @@ To create the `.gitlab/issue_templates` directory: To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-a-new-issue) and see if you can choose a description template. -## Creating merge request templates +## Create a merge request template Similarly to issue templates, create a new Markdown (`.md`) file inside the `.gitlab/merge_request_templates/` directory in your repository. Commit and push to your default branch. -## Using the templates +## Use the templates Let's take for example that you've created the file `.gitlab/issue_templates/Bug.md`. This enables the `Bug` dropdown option when creating or editing issues. When @@ -85,42 +89,85 @@ For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_templat  -## Setting a default template for merge requests and issues **(PREMIUM)** +### Set an issue and merge request description template at group level **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - It's disabled by default on GitLab.com. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to + [enable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). + +Templates can be useful because you can create a template once and use it multiple times. +To re-use templates [you've created](../project/description_templates.md#create-an-issue-template): + +1. Go to the group's **Settings > General > Templates**. +1. From the dropdown, select your template project as the template repository at group level. + + + +### Set an issue and merge request description template at instance level **(PREMIUM ONLY)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - It's disabled by default on GitLab.com. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to + [enable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). + +Similar to group templates, issue and merge request templates can also be set up at the instance level. +This results in those templates being available in all projects within the instance. +Only instance administrators can set instance-level templates. + +To set the instance-level description template repository: + +1. Select the **Admin Area** icon (**{admin}**). +1. Go to **Settings > Templates**. +1. From the dropdown, select your template project as the template repository at instance level. + +Learn more about [instance template repository](../admin_area/settings/instance_template_repository.md). + + -> - Moved to GitLab Premium in 13.9. +### Set a default template for merge requests and issues **(PREMIUM)** The visibility of issues or merge requests should be set to either "Everyone with access" or "Only Project Members" in your project's **Settings / Visibility, project features, permissions** section, otherwise the template text areas don't show. This is the default behavior, so in most cases you should be fine. +To set a default description template for merge requests: + 1. Go to your project's **Settings**. -1. Click **Expand** under the **Merge requests** header. +1. Select **Expand** under the **Merge requests** header. 1. Fill in the **Default description template for merge requests** text area. -1. Click **Expand** under **Default issue template**. +1. Select **Save changes**. + +To set a default description template for issues: + +1. Select **Expand** under **Default issue template**. 1. Fill in the **Default description template for issues** text area. - Since GitLab merge request and issues support [Markdown](../markdown.md), you can use it to format - headings, lists, and so on. - +Because GitLab merge request and issues support [Markdown](../markdown.md), you can use it to format +headings, lists, and so on. - +Now, every time a new merge request or issue is created, it's pre-filled with the text you entered +in the templates. -After you add the description, hit **Save changes** for the settings to take -effect. Now, every time a new merge request or issue is created, it is -pre-filled with the text you entered in the template(s). +[GitLab versions 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/885) +provide `issues_template` and `merge_requests_template` attributes in the +[Projects API](../../api/projects.md) to help you keep your templates up to date. ## Description template example -We make use of description templates for issues and merge requests in the GitLab project. -For some examples, refer to the [`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab). +We use description templates for issues and merge requests in the +[`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab) of the +GitLab project, which you can refer to for some examples. NOTE: It's possible to use [quick actions](quick_actions.md) in description templates to quickly add labels, assignees, and milestones. The quick actions are only executed if the user submitting the issue or merge request has the permissions to perform the relevant actions. -Here is an example of a Bug report template: +Here is an example of a bug report template: ```markdown ## Summary @@ -159,3 +206,28 @@ it's very hard to read otherwise.) /cc @project-manager /assign @qa-tester ``` + +## Enable or disable issue and merge request description templates at group and instance level + +Setting issue and merge request description templates at group and instance levels +is under development and not ready for production use. It is deployed behind a +feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:inherited_issuable_templates) +``` + +To disable it: + +```ruby +Feature.disable(:inherited_issuable_templates) +``` + +The feature flag affects these features: + +- Setting a templates project as issue and merge request description templates source at group level. +- Setting a templates project as issue and merge request description templates source at instance level. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 5c24ec6caf6..4edb6fbdad9 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -36,9 +36,9 @@ GitLab supports two different modes of file locking: Locks can be created by any person who has at least [Developer permissions](../permissions.md) to the repository. -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 +Only the user who locked the file or directory can edit locked files. Other +users are prevented from modifying locked files by pushing, merging, +or any other means, and are shown an error like: `The path '.gitignore' is locked by Administrator`. ## Exclusive file locks **(FREE)** @@ -60,7 +60,7 @@ Before getting started, make sure you have [Git LFS installed](../../topics/git/ git-lfs --version ``` -If it doesn't recognize this command, you'll have to install it. There are +If it doesn't recognize this command, you must 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: @@ -70,7 +70,7 @@ brew install git-lfs Once installed, **open your local repository in a terminal window** and install Git LFS in your repository. If you're sure that LFS is already installed, -you can skip this step. If you're unsure, re-installing it won't do any harm: +you can skip this step. If you're unsure, re-installing it does no harm: ```shell git lfs install @@ -84,14 +84,14 @@ You need [Maintainer permissions](../permissions.md) to configure Exclusive File Locks for your project through the command line. 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 +kind of files are lockable. The following command stores PNG files in LFS and flag them as lockable: ```shell git lfs track "*.png" --lockable ``` -After executing the above command a file named `.gitattributes` will be +After executing the above command a file named `.gitattributes` is created or updated with the following content: ```shell @@ -110,9 +110,9 @@ implements the LFS File Locking API). To do that you can edit the The `.gitattributes` file is key to the process and **must** be pushed to the remote repository for the changes to take effect. -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). +After a file type has been registered as lockable, Git LFS makes +them read-only on the file system automatically. This means you +must **lock the file** before [editing it](#edit-lockable-files). ### Lock files @@ -168,7 +168,7 @@ 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 +On the repository file tree, GitLab displays an LFS badge for files tracked by Git LFS plus a padlock icon on exclusively-locked files:  @@ -176,7 +176,7 @@ 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: -When you rename an exclusively-locked file, the lock is lost. You'll have to +When you rename an exclusively-locked file, the lock is lost. You must lock it again to keep it locked. ### Edit lockable files @@ -204,7 +204,7 @@ 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 +Changes to locked files on the default branch are blocked, including merge requests that modify locked files. Unlock the file to allow changes. ### Lock a file or a directory @@ -216,10 +216,10 @@ To lock a file:  -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. +An **Unlock** button is displayed if the file is already locked, and +is 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 +If you did not lock the file, hovering your cursor over the button shows who locked the file. ### View and remove existing locks diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 2806f6e48d1..11d1db195e1 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -17,7 +17,7 @@ directory of your repository and push it to the default branch of your project. ## Encoding Requirements The `.gitattributes` file _must_ be encoded in UTF-8 and _must not_ contain a -Byte Order Mark. If a different encoding is used, the file's contents will be +Byte Order Mark. If a different encoding is used, the file's contents are ignored. ## Syntax Highlighting diff --git a/doc/user/project/img/autocomplete_characters_example1_v12_0.png b/doc/user/project/img/autocomplete_characters_example1_v12_0.png Binary files differdeleted file mode 100644 index 9c6fa923b80..00000000000 --- a/doc/user/project/img/autocomplete_characters_example1_v12_0.png +++ /dev/null diff --git a/doc/user/project/img/autocomplete_characters_example2_v12_0.png b/doc/user/project/img/autocomplete_characters_example2_v12_0.png Binary files differdeleted file mode 100644 index b2e8a782a0b..00000000000 --- a/doc/user/project/img/autocomplete_characters_example2_v12_0.png +++ /dev/null diff --git a/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png b/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png Binary files differdeleted file mode 100644 index fc2893aa4d5..00000000000 --- a/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png +++ /dev/null diff --git a/doc/user/project/img/code_owners_approval_new_protected_branch_v13_10.png b/doc/user/project/img/code_owners_approval_new_protected_branch_v13_10.png Binary files differnew file mode 100644 index 00000000000..ee4ee2c6d71 --- /dev/null +++ b/doc/user/project/img/code_owners_approval_new_protected_branch_v13_10.png diff --git a/doc/user/project/img/code_owners_approval_protected_branch_v12_4.png b/doc/user/project/img/code_owners_approval_protected_branch_v12_4.png Binary files differdeleted file mode 100644 index 59da6874d14..00000000000 --- a/doc/user/project/img/code_owners_approval_protected_branch_v12_4.png +++ /dev/null diff --git a/doc/user/project/img/code_owners_approval_protected_branch_v13_10.png b/doc/user/project/img/code_owners_approval_protected_branch_v13_10.png Binary files differnew file mode 100644 index 00000000000..220eb207132 --- /dev/null +++ b/doc/user/project/img/code_owners_approval_protected_branch_v13_10.png diff --git a/doc/user/project/img/description_templates_issue_settings.png b/doc/user/project/img/description_templates_issue_settings.png Binary files differdeleted file mode 100644 index 7f354f7c288..00000000000 --- a/doc/user/project/img/description_templates_issue_settings.png +++ /dev/null diff --git a/doc/user/project/img/description_templates_merge_request_settings.png b/doc/user/project/img/description_templates_merge_request_settings.png Binary files differdeleted file mode 100644 index 587367bf2fe..00000000000 --- a/doc/user/project/img/description_templates_merge_request_settings.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_remove_issue_v13_6.png b/doc/user/project/img/issue_boards_remove_issue_v13_6.png Binary files differdeleted file mode 100644 index c980759ad0c..00000000000 --- a/doc/user/project/img/issue_boards_remove_issue_v13_6.png +++ /dev/null diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index c135b1be54a..eb426a9f126 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -49,8 +49,9 @@ The steps you take depend on whether you are importing from GitHub.com or GitHub [GitHub Rake task](../../../administration/raketasks/github_import.md) to import projects without the constraints of a [Sidekiq](../../../development/sidekiq_style_guide.md) worker. - If you're importing from GitHub Enterprise to your self-managed GitLab instance, you must first enable - [GitHub integration](../../../integration/github.md). However, you cannot import projects from GitHub Enterprise to GitLab.com. -- If you're importing from GitHub.com to your self-managed GitLab instance, you do not need to set up GitHub integration. + [GitHub integration](../../../integration/github.md). + - To import projects from GitHub Enterprise to GitLab.com, use the [Import API](../../../api/import.md). +- If you're importing from GitHub.com to your self-managed GitLab instance, you do not need to set up GitHub integration. You can use the [Import API](../../../api/import.md). ## How it works @@ -62,7 +63,7 @@ must meet one of the following conditions prior to the import: - Have previously logged in to a GitLab account using the GitHub icon. - Have a GitHub account with a publicly visible - [primary email address](https://docs.github.com/en/free-pro-team@latest/rest/reference/users#get-a-user) + [primary email address](https://docs.github.com/en/rest/reference/users#get-a-user) on their profile that matches their GitLab account's primary or secondary email address. If a user referenced in the project is not found in the GitLab database, the project creator (typically the user @@ -91,7 +92,7 @@ Before you begin, ensure that any GitHub users who you want to map to GitLab use - A GitLab account that has logged in using the GitHub icon \- or - -- A GitLab account with an email address that matches the [publicly visible email address](https://docs.github.com/en/free-pro-team@latest/rest/reference/users#get-a-user) in the profile of the GitHub user +- A GitLab account with an email address that matches the [publicly visible email address](https://docs.github.com/en/rest/reference/users#get-a-user) in the profile of the GitHub user User-matching attempts occur in that order, and if a user is not identified either way, the activity is associated with the user account that is performing the import. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index a8ab1cbbb63..7e5801a2382 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -154,9 +154,7 @@ There are numerous [APIs](../../api/README.md) to use with your projects: - [Aliases](../../api/project_aliases.md) - [DORA4 Analytics](../../api/dora4_project_analytics.md) -## DORA4 analytics overview **(ULTIMATE ONLY)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in GitLab [Ultimate](https://about.gitlab.com/pricing/) 13.7 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). +## DORA4 analytics overview Project details include the following analytics: diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index fb9314f7504..3b012ab4430 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Atlassian Bamboo CI Service +# Atlassian Bamboo CI Service **(FREE)** GitLab provides integration with Atlassian Bamboo for continuous integration. When configured, pushes to a project trigger a build in Bamboo automatically. diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 4e2ee9b3662..7e14515d98e 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Bugzilla Service +# Bugzilla Service **(FREE)** Navigate to the [Integrations page](overview.md#accessing-integrations), select the **Bugzilla** service and fill in the required details as described diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 143f0e2a25d..9cc4e980212 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Custom Issue Tracker service +# Custom Issue Tracker service **(FREE)** To enable the Custom Issue Tracker integration in a project: diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 8e0a167a968..624c0252f23 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Discord Notifications service +# Discord Notifications service **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22684) in GitLab 11.6. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index 2274913d349..4970e20974b 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Enabling emails on push +# Enabling emails on push **(FREE)** By enabling this service, you receive email notifications for every change that is pushed to your project. diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 5ef36ff4074..1c0309cab87 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -20,7 +20,7 @@ and is automatically configured on [GitHub import](../../../integration/github.m ### Complete these steps on GitHub -This integration requires a [GitHub API token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) +This integration requires a [GitHub API token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with `repo:status` access granted: 1. Go to your "Personal access tokens" page at <https://github.com/settings/tokens> diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 06dcca6eb44..d0efebd4da7 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Hangouts Chat service +# Hangouts Chat service **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/43756) in GitLab 11.2. diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md index 7b90d8d7cfd..f66fc0a0f6a 100644 --- a/doc/user/project/integrations/hipchat.md +++ b/doc/user/project/integrations/hipchat.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Atlassian HipChat +# Atlassian HipChat **(FREE)** GitLab provides a way to send HipChat notifications upon a number of events, such as when a user pushes code, creates a branch or tag, adds a comment, and diff --git a/doc/user/project/integrations/img/mattermost_config_help.png b/doc/user/project/integrations/img/mattermost_config_help.png Binary files differdeleted file mode 100644 index dd3481bc1f6..00000000000 --- a/doc/user/project/integrations/img/mattermost_config_help.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_console_integrations.png b/doc/user/project/integrations/img/mattermost_console_integrations.png Binary files differdeleted file mode 100644 index 625b57d4dc9..00000000000 --- a/doc/user/project/integrations/img/mattermost_console_integrations.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_goto_console.png b/doc/user/project/integrations/img/mattermost_goto_console.png Binary files differdeleted file mode 100644 index 8bacbe485f4..00000000000 --- a/doc/user/project/integrations/img/mattermost_goto_console.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_slash_command_configuration.png b/doc/user/project/integrations/img/mattermost_slash_command_configuration.png Binary files differdeleted file mode 100644 index f9e9de439ca..00000000000 --- a/doc/user/project/integrations/img/mattermost_slash_command_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_slash_command_token.png b/doc/user/project/integrations/img/mattermost_slash_command_token.png Binary files differdeleted file mode 100644 index c38f37c203c..00000000000 --- a/doc/user/project/integrations/img/mattermost_slash_command_token.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_team_integrations.png b/doc/user/project/integrations/img/mattermost_team_integrations.png Binary files differdeleted file mode 100644 index c2b68256e11..00000000000 --- a/doc/user/project/integrations/img/mattermost_team_integrations.png +++ /dev/null diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 0e5163e992a..5628a9bc5e5 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project integrations +# Project integrations **(FREE)** You can find the available integrations under your project's **Settings > Integrations** page. You need to have at least diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 58f7ea3279f..e75561b3ddb 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Irker IRC Gateway +# Irker IRC Gateway **(FREE)** GitLab provides a way to push update messages to an Irker server. When configured, pushes to a project trigger the service to send data directly diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 5857c3da803..0878e1c9386 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Jira integration +# GitLab Jira integration **(FREE)** You can use Jira to track work implemented in GitLab. The Jira integration with GitLab makes the process of working across these systems more efficient. diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index e9f30f32308..8e25af3f884 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Create an API token in Jira on Atlassian cloud +# Create an API token in Jira on Atlassian cloud **(FREE)** For [integrations with Jira](jira.md), an API token is needed when integrating with Jira on Atlassian cloud. To create an API token: diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index 6a1529f001a..6b938238320 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Jira integrations +# Jira integrations **(FREE)** GitLab can be integrated with [Jira](https://www.atlassian.com/software/jira). diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index 5bb17388a1e..b1ab2076dc0 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Create Jira Server username and password +# Create Jira Server username and password **(FREE)** For [integrations with Jira](jira.md), you must create a user account in Jira to have access to all projects that need to integrate with GitLab. diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index db190f47b01..6a93fc0fb06 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Mattermost Notifications Service +# Mattermost Notifications Service **(FREE)** The Mattermost Notifications Service allows your GitLab project to send events (e.g., `issue created`) to your existing Mattermost team as notifications. This requires configurations in both Mattermost and GitLab. diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 6c8a0ded2ae..20f5b73b37c 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -4,118 +4,121 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Mattermost slash commands +# Mattermost slash commands **(FREE)** -> Introduced in GitLab 8.14 +If your team uses [Mattermost](https://mattermost.com/) as a chat service, you can +integrate GitLab commands into Mattermost chat. This integration enables users to +run common operations, such as creating a GitLab issue, from the Mattermost chat +environment. -Mattermost commands give users an extra interface to perform common operations -from the chat environment. This allows one to, for example, create an issue as -soon as the idea was discussed in Mattermost. - -GitLab can also send events (e.g., `issue created`) to Mattermost as notifications. -This is the separately configured [Mattermost Notifications Service](mattermost.md). +GitLab can also send events (such as `issue created`) to Mattermost as part of the +separately configured [Mattermost Notifications Service](mattermost.md). ## Prerequisites -Mattermost 3.4 and up is required. +Mattermost [3.4 or later](https://mattermost.com/blog/category/releases/) is required. +GitLab provides different methods of configuring Mattermost slash commands, depending +on your configuration: -If you have the Omnibus GitLab package installed, Mattermost is already bundled -in it. All you have to do is configure it. Read more in the -[Omnibus GitLab Mattermost documentation](https://docs.gitlab.com/omnibus/gitlab-mattermost/). +- **Omnibus GitLab installations**: Mattermost is bundled with + [Omnibus GitLab](https://docs.gitlab.com/omnibus/). To configure Mattermost for Omnibus GitLab, read the + [Omnibus GitLab Mattermost documentation](https://docs.gitlab.com/omnibus/gitlab-mattermost/). +- **If Mattermost is installed on the same server as GitLab**, use the + [automated configuration](#automated-configuration). +- **For all other installations**, use the [manual configuration](#manual-configuration). ## Automated configuration If Mattermost is installed on the same server as GitLab, the configuration process can be done for you by GitLab. -Go to the Mattermost Slash Command service on your project and click the 'Add to Mattermost' button. +Go to the Mattermost Slash Command service on your project and click **Add to Mattermost** button. ## Manual configuration -The configuration consists of two parts. First you need to enable the slash -commands in Mattermost and then enable the service in GitLab. - -### Step 1. Enable custom slash commands in Mattermost - -This step is only required when using a source install. Omnibus installs are -preconfigured with the right settings. - -The first thing to do in Mattermost is to enable custom slash commands from -the administrator console. - -1. Log in with an account that has administrator privileges and navigate to the system - console. - -  - -1. Click **Integration Management** and set **Enable Custom Slash Commands**, - **Enable integrations to override usernames**, and **Enable - integrations to override profile picture icons** to true +To manually configure slash commands in Mattermost, you must: -  +1. [Enable custom slash commands](#enable-custom-slash-commands) in Mattermost. +1. [Get configuration values](#get-configuration-values-from-gitlab) from GitLab. +1. [Create a new slash command](#create-a-slash-command) in Mattermost. +1. [Provide the Mattermost token](#provide-the-mattermost-token-to-gitlab) to GitLab. -1. Click **Save** at the bottom to save the changes. +### Enable custom slash commands -### Step 2. Open the Mattermost slash commands service in GitLab +NOTE: +Omnibus GitLab installations are preconfigured. This step is required only for +installations from source. -1. Open a new tab for GitLab, go to your project's - [Integrations page](overview.md#accessing-integrations) - and select the **Mattermost command** service to configure it. - A screen appears with all the values you need to copy in Mattermost as - described in the next step. Leave the window open. +To enable custom slash commands from the Mattermost administrator console: - NOTE: - GitLab offers some values for the Mattermost settings. Only **Request URL** is required - as offered, all the others are just suggestions. +1. Sign in to Mattermost as a user with administrator privileges. +1. Next to your username, click the **{ellipsis_v}** **Settings** icon, and + select **System Console**. +1. Select **Integration Management**, and set these values to `TRUE`: + - **Enable Custom Slash Commands** + - **Enable integrations to override usernames** + - **Enable integrations to override profile picture icons** +1. Click **Save**, but do not close this browser tab, because you need it in + a later step. -  +### Get configuration values from GitLab -1. Proceed to the next step and create a slash command in Mattermost with the - above values. +After you enable custom slash commands in Mattermost, you need configuration +information from GitLab. To get this information: -### Step 3. Create a new custom slash command in Mattermost +1. In a different browser tab than your current Mattermost session, sign in to + GitLab as a user with [administrator permissions](../../permissions.md). +1. In the top navigation bar, go to **{admin}** **Admin Area**. +1. In the left menu, go to **Settings > Integrations** and select + **Mattermost slash commands**. +1. GitLab displays potential values for Mattermost settings. Copy the **Request URL** + as you need it for the next step. All other values are suggestions. +1. Do not close this browser tab, because you need it in future steps. -Now that you have enabled custom slash commands in Mattermost and opened -the Mattermost slash commands service in GitLab, it's time to copy these values -in a new slash command. +Next, create a slash command in Mattermost with the values from GitLab. -1. Back to Mattermost, under your team page settings, you should see the - **Integrations** option. +### Create a slash command -  +To create a slash command, you need the values you obtained from GitLab in +the previous step: -1. Go to the **Slash Commands** integration and add a new one by clicking the - **Add Slash Command** button. +1. In the Mattermost tab you left open when you + [enabled custom slash commands](#enable-custom-slash-commands), go to your + team page. +1. Click the **{ellipsis_v}** **Settings** icon, and select **Integrations**. +1. In the left menu, select **Slash commands**. +1. Click **Add Slash Command**:  - -1. Fill in the options for the custom command as described in - [step 2](#step-2-open-the-mattermost-slash-commands-service-in-gitlab). - - NOTE: - If you plan on connecting multiple projects, pick a slash command trigger - word that relates to your projects such as `/gitlab-project-name` or even - just `/project-name`. Only use `/gitlab` if you plan to only connect a single - project to your Mattermost team. - -  - -1. After you set up all the values, copy the token (we use it below) and - click **Done**. - -  - -### Step 4. Copy the Mattermost token into the Mattermost slash command service - -1. In GitLab, paste the Mattermost token you copied in the previous step and +1. Provide a **Display Name** and **Description** for your new command. +1. Provide a **Command Trigger Word** according to your application's configuration: + + - **If you intend to only connect one project to your Mattermost team**: Use + `/gitlab` for your trigger word. + - **If you intend to connect multiple projects**: Use a trigger word that relates + to your project, such as `/project-name` or `/gitlab-project-name`. +1. For **Request URL**, provide the value you copied from GitLab when you + [viewed configuration values](#get-configuration-values-from-gitlab). +1. For all other values, you may use the suggestions from GitLab or use your + preferred values. +1. Copy the **Token** value, as you need it in a later step, and click **Done**. + +### Provide the Mattermost token to GitLab + +When you create a new slash command in Mattermost, it generates a token you must +provide to GitLab: + +1. In the GitLab browser tab from + [getting configuration values from GitLab](#get-configuration-values-from-gitlab), + select the **Active** check box to enable this configuration. +1. In the **Token** field, paste the token you obtained from Mattermost. ensure that the **Active** toggle is enabled.  1. Click **Save changes** for the changes to take effect. -You are now set to start using slash commands in Mattermost that talk to the -GitLab project you configured. +Your slash command can now communicate with your GitLab project. ## Authorizing Mattermost to interact with GitLab @@ -132,7 +135,7 @@ GitLab using the Mattermost commands. ## Available slash commands -The available slash commands are: +The available slash commands for Mattermost are: | Command | Description | Example | | ------- | ----------- | ------- | @@ -152,7 +155,7 @@ the [permissions you have on the project](../../permissions.md#project-members-p ## Troubleshooting -If an event is not being triggered, confirm that the channel you're using is a public one, as +If an event is not being triggered, confirm that the channel you're using is a public one. Mattermost webhooks do not have access to private channels. If a private channel is required, you can edit the webhook's channel in Mattermost and diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 136da05d0e8..41e0938fc3b 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Microsoft Teams service +# Microsoft Teams service **(FREE)** ## On Microsoft Teams diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index 18f0ad6b275..934510fd155 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Mock CI Service +# Mock CI Service **(FREE)** **NB: This service is only listed if you are in a development environment!** diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index b22a7c0295e..f6590b6ba2f 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Integrations +# Integrations **(FREE)** Integrations allow you to integrate GitLab with other applications. They are a bit like plugins in that they allow a lot of freedom in adding diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 4a88010a343..04abb922175 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -6,31 +6,38 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Monitoring AWS resources **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 - -GitLab has support for automatically detecting and monitoring AWS resources, starting with the [Elastic Load Balancer](https://aws.amazon.com/elasticloadbalancing/). This is provided by leveraging the official [Cloudwatch exporter](https://github.com/prometheus/cloudwatch_exporter), which translates [Cloudwatch metrics](https://aws.amazon.com/cloudwatch/) into a Prometheus readable form. +GitLab supports automatically detecting and monitoring AWS resources, starting +with the [Elastic Load Balancer](https://aws.amazon.com/elasticloadbalancing/) (ELB). +This is provided by leveraging the official [Cloudwatch exporter](https://github.com/prometheus/cloudwatch_exporter), which translates [Cloudwatch metrics](https://aws.amazon.com/cloudwatch/) into +a Prometheus readable form. ## Requirements -The [Prometheus service](../prometheus.md) must be enabled. +You must enable the [Prometheus service](../prometheus.md). -## Metrics supported +## Supported metrics -| Name | Query | -| ---- | ----- | +| Name | Query | +|----------------------|-------| | Throughput (req/sec) | `sum(aws_elb_request_count_sum{%{environment_filter}}) / 60` | -| Latency (ms) | `avg(aws_elb_latency_average{%{environment_filter}}) * 1000` | -| HTTP Error Rate (%) | `sum(aws_elb_httpcode_backend_5_xx_sum{%{environment_filter}}) / sum(aws_elb_request_count_sum{%{environment_filter}})` | +| Latency (ms) | `avg(aws_elb_latency_average{%{environment_filter}}) * 1000` | +| HTTP Error Rate (%) | `sum(aws_elb_httpcode_backend_5_xx_sum{%{environment_filter}}) / sum(aws_elb_request_count_sum{%{environment_filter}})` | ## Configuring Prometheus to monitor for Cloudwatch metrics -To get started with Cloudwatch monitoring, you should install and configure the [Cloudwatch exporter](https://github.com/prometheus/cloudwatch_exporter) which retrieves and parses the specified Cloudwatch metrics and translates them into a Prometheus monitoring endpoint. +To get started with Cloudwatch monitoring, install and configure the +[Cloudwatch exporter](https://github.com/prometheus/cloudwatch_exporter). The +Cloudwatch exporter retrieves and parses the specified Cloudwatch metrics, and +translates them into a Prometheus monitoring endpoint. -Right now, the only AWS resource supported is the Elastic Load Balancer, whose Cloudwatch metrics are [documented here](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html). +The only supported AWS resource is the Elastic Load Balancer, whose Cloudwatch +metrics are [documented here](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html). -A sample Cloudwatch Exporter configuration file, configured for basic AWS ELB monitoring, is [available for download](../samples/cloudwatch.yml). +You can [download a sample Cloudwatch Exporter configuration file](../samples/cloudwatch.yml) +that's configured for basic AWS ELB monitoring. ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). +To isolate and display only the relevant metrics for a given environment, +GitLab needs a method to detect which labels are associated. To do this, GitLab +[looks for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index 38d6194b390..256ffe84ee2 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Redmine Service +# Redmine Service **(FREE)** 1. To enable the Redmine integration in a project, navigate to the [Integrations page](overview.md#accessing-integrations), click diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index 1de69f60a34..bdc05552c31 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# ServiceNow integration +# ServiceNow integration **(FREE)** ServiceNow offers several integrations to help centralize and automate your management of GitLab workflows. diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index 7507792bb02..66810d8a01b 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Service templates +# Service templates **(FREE)** WARNING: Service templates are [deprecated and scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index ab798675278..17d1c3adcb5 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Slack Notifications Service +# Slack Notifications Service **(FREE)** The Slack Notifications Service allows your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index e8dcb577aba..3e5e368722e 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Unify Circuit service +# Unify Circuit service **(FREE)** The Unify Circuit service sends notifications from GitLab to the conversation for which the webhook was created. diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 8a3383fd0e7..6820412808f 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Webex Teams service +# Webex Teams service **(FREE)** You can configure GitLab to send notifications to a Webex Teams space. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 0cf01adef13..bf289c9707c 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Webhooks +# Webhooks **(FREE)** Project webhooks allow you to trigger a percent-encoded URL if, for example, new code is pushed or a new issue is created. You can configure webhooks to listen for specific events @@ -1133,6 +1133,10 @@ X-Gitlab-Event: Pipeline Hook "artifacts_file":{ "filename": null, "size": null + }, + "environment": { + "name": "production", + "action": "start" } }, { @@ -1167,7 +1171,8 @@ X-Gitlab-Event: Pipeline Hook "artifacts_file":{ "filename": null, "size": null - } + }, + "environment": null }, { "id": 378, @@ -1200,7 +1205,8 @@ X-Gitlab-Event: Pipeline Hook "artifacts_file":{ "filename": null, "size": null - } + }, + "environment": null }, { "id": 376, @@ -1233,7 +1239,8 @@ X-Gitlab-Event: Pipeline Hook "artifacts_file":{ "filename": null, "size": null - } + }, + "environment": null }, { "id": 379, @@ -1257,6 +1264,10 @@ X-Gitlab-Event: Pipeline Hook "artifacts_file":{ "filename": null, "size": null + }, + "environment": { + "name": "staging", + "action": "start" } } ] @@ -1329,7 +1340,8 @@ X-Gitlab-Event: Job Hook "linux", "docker" ] - } + }, + "environment": null } ``` @@ -1554,7 +1566,7 @@ X-Gitlab-Event: Subgroup Hook ``` NOTE: -Webhooks for when a [subgroup is removed from a group](#subgroup-removed-from-a-group) are not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transferring-groups) +Webhooks for when a [subgroup is removed from a group](#subgroup-removed-from-a-group) are not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transfer-a-group) ### Feature Flag events diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index f9b3c083a54..f9f61de9d6b 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# YouTrack Service +# YouTrack Service **(FREE)** JetBrains [YouTrack](https://www.jetbrains.com/help/youtrack/standalone/YouTrack-Documentation.html) is a web-based issue tracking and project management platform. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index e4f42b97b84..a537972dff7 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -87,9 +87,9 @@ To delete the currently active issue board: You can tailor GitLab issue boards to your own preferred workflow. Here are some common use cases for issue boards. -For examples of using issue boards along with [epics](../group/epics/index.md) **(PREMIUM)**, -[issue health status](issues/index.md#health-status) **(ULTIMATE)**, and -[scoped labels](labels.md#scoped-labels) **(PREMIUM)** for various Agile frameworks, check: +For examples of using issue boards along with [epics](../group/epics/index.md), +[issue health status](issues/index.md#health-status), and +[scoped labels](labels.md#scoped-labels) for various Agile frameworks, check: - The [How to use GitLab for Agile portfolio planning and project management](https://about.gitlab.com/blog/2020/11/11/gitlab-for-agile-portfolio-planning-project-management/) blog post (November 2020) - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -154,7 +154,7 @@ for them. NOTE: For a broader use case, please see the blog post -[GitLab Workflow, an Overview](https://about.gitlab.com/blog/2016/10/25/gitlab-workflow-an-overview/#gitlab-workflow-use-case-scenario). +[GitLab Workflow, an Overview](https://about.gitlab.com/topics/version-control/what-is-gitlab-workflow/#gitlab-workflow-a-use-case-scenario). For a real use case example, you can read why [Codepen decided to adopt issue boards](https://about.gitlab.com/blog/2017/01/27/codepen-welcome-to-gitlab/#project-management-everything-in-one-place) to improve their workflow with multiple boards. @@ -277,6 +277,32 @@ group and its descendant subgroups. Similarly, you can only filter by group labe boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only group-level objects are available. +#### GraphQL-based sidebar for group issue boards **(PREMIUM)** + +<!-- When the feature flag is removed, integrate this section into the above ("Group issue boards"). --> + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-graphql-based-sidebar-for-group-issue-boards). **(PREMIUM SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +The work-in-progress GraphQL-based sidebar for group issue boards brings better performance and the +ability to edit issue titles in the issue sidebar. + +To **edit an issue's title** in the issue sidebar: + +1. In a group issue board, select the issue card. The issue sidebar opens on the right. +1. Next to the issue's title, select **Edit**. + +This is work in progress as of GitLab 13.9. Learn more about the known issues in +[MR 51480](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51480). + +<!-- Add this at the end of the file --> + ### Assignee lists **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5784) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.0. @@ -317,6 +343,7 @@ As in other list types, click the trash icon to remove a list. > - Grouping by epic [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3352) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. > - Editing issue titles in the issue sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232745) in GitLab 13.8. +> - Editing iteration in the issue sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290232) in GitLab 13.9. With swimlanes you can visualize issues grouped by epic. Your issue board keeps all the other features, but with a different visual organization of issues. @@ -456,31 +483,16 @@ the list by filtering by the following: - Release - Weight -#### Enable or disable adding issues to the list **(FREE SELF)** - -Adding issues to the list is deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:add_issues_button) -``` - -To disable it: - -```ruby -Feature.disable(:add_issues_button) -``` - ### Remove an issue from a list -Removing an issue from a list can be done by clicking the issue card and then -clicking the **Remove from board** button in the sidebar. The -respective label is removed. +> The **Remove from board** button was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229507) in GitLab 13.10. + +When an issue should no longer belong to a list, you can remove it. +The steps depend on the scope of the list: - +1. To open the right sidebar, select the issue card. +1. Remove what's keeping the issue in the list. + If it's a label list, remove the label. If it's an [assignee list](#assignee-lists), unassign the user. ### Filter issues @@ -593,3 +605,40 @@ A few things to remember: - 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 appear. + +## Enable or disable GraphQL-based sidebar for group issue boards **(PREMIUM SELF)** + +GraphQL-based sidebar for group issue boards is under development and not ready for production use. +It is deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:graphql_board_lists) +``` + +To disable it: + +```ruby +Feature.disable(:graphql_board_lists) +``` + +## Enable or disable adding issues to the list **(FREE SELF)** + +Adding issues to the list is deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:add_issues_button) +``` + +To disable it: + +```ruby +Feature.disable(:add_issues_button) +``` diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index d81fe19c5b9..f98e94c66ae 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -17,7 +17,7 @@ team members can join swiftly without requesting a link. ## Adding a Zoom meeting to an issue To associate a Zoom meeting with an issue, you can use GitLab -[quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). +[quick actions](../quick_actions.md#issues-merge-requests-and-epics). In an issue, leave a comment using the `/zoom` quick action followed by a valid Zoom link: diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index b6dff0842d8..f5eb8dd5a4d 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -257,6 +257,6 @@ This will be rendered as: > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/225205) in GitLab 13.2. User activity events on designs (creation, deletion, and updates) are tracked by GitLab and -displayed on the [user profile](../../profile/index.md#user-profile), +displayed on the [user profile](../../profile/index.md#access-your-user-profile), [group](../../group/index.md#view-group-activity), and [project](../working_with_projects.md#project-activity) activity pages. diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index e398c6f86d0..7c8ba4edd6b 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -137,7 +137,7 @@ You can mark two issues as related, so that when viewing one, the other is alway listed in its [Related Issues](related_issues.md) section. This can help display important context, such as past work, dependencies, or duplicates. -Users on [GitLab Starter, GitLab Bronze, and higher tiers](https://about.gitlab.com/pricing/), can +Users of [GitLab Premium](https://about.gitlab.com/pricing/) or higher can also mark issues as blocking or blocked by another issue. ### Crosslinking issues @@ -162,9 +162,9 @@ Up to five similar issues, sorted by most recently updated, are displayed below ### Health status **(ULTIMATE)** -> - [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. -> - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in GitLab Ultimate 12.10. +> - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in GitLab Ultimate 13.4 and later. +> - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in GitLab Ultimate 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. To help you track issue statuses, you can assign a status to each issue. @@ -184,7 +184,7 @@ You can then see issue statuses in the [issue list](#issues-list) and the ## Other Issue actions -- [Create an issue from a template](../../project/description_templates.md#using-the-templates) +- [Create an issue from a template](../../project/description_templates.md#use-the-templates) - [Set a due date](due_dates.md) - [Bulk edit issues](../bulk_editing.md) - From the Issues List, select multiple issues in order to change their status, assignee, milestone, or labels in bulk. @@ -197,18 +197,18 @@ You can then see issue statuses in the [issue list](#issues-list) and the ## Enable or disable cached issue count **(FREE SELF)** Cached issue count in the left sidebar is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. +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. +can disable it. -To enable it: +To disable it: ```ruby -Feature.enable(:cached_sidebar_open_issues_count) +Feature.disable(:cached_sidebar_open_issues_count) ``` -To disable it: +To enable it: ```ruby -Feature.disable(:cached_sidebar_open_issues_count) +Feature.enable(:cached_sidebar_open_issues_count) ``` diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index c3adce33826..90c918792d7 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -186,7 +186,7 @@ This icon is only displayed if the user has permission to edit the issue. ### Description The plain text title and description of the issue fill the top center of the issue page. -The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), +The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown), allowing many formatting options. [In GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) and later, changes to an @@ -249,7 +249,7 @@ Also: ### Create Merge Request -Create a new branch and [**Draft** merge request](../merge_requests/work_in_progress_merge_requests.md) +Create a new branch and [**Draft** merge request](../merge_requests/drafts.md) in one action. The branch is named `issuenumber-title` by default, but you can choose any name, and GitLab verifies that it is not already in use. The merge request inherits the milestone and labels of the issue, and is set to automatically @@ -281,7 +281,7 @@ or newest items to be shown first. ### Comments Collaborate in the issue by posting comments in its thread. This text field also fully -supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). +supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). ### Submit comment, start a thread, or comment and close @@ -301,7 +301,7 @@ You can also close the issue from here, so you don't need to scroll to the top o > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31103) in GitLab 12.3. You can attach and remove Zoom meetings to issues using the `/zoom` and `/remove_zoom` [quick actions](../quick_actions.md) as part of -[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). +[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). Attaching a [Zoom](https://zoom.us) call an issue results in a **Join Zoom meeting** button at the top of the issue, just under the header. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index f1739726cf8..cfb22881431 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -298,7 +298,7 @@ To promote an issue to an epic: 1. In an issue, select the vertical ellipsis (**{ellipsis_v}**) button. 1. Select **Promote to epic**. -Alternatively, you can use the `/promote` [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). +Alternatively, you can use the `/promote` [quick action](../quick_actions.md#issues-merge-requests-and-epics). Read more about promoting an issue to an epic on the [Manage epics page](../../group/epics/manage_epics.md#promote-an-issue-to-an-epic). @@ -313,5 +313,5 @@ To add an issue to an [iteration](../../group/iterations/index.md): 1. Click an iteration you'd like to associate this issue with. You can also use the `/iteration` -[quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) +[quick action](../quick_actions.md#issues-merge-requests-and-epics) in a comment or description field. diff --git a/doc/user/project/members/img/project_members_filter_v12_6.png b/doc/user/project/members/img/project_members_filter_v12_6.png Binary files differdeleted file mode 100644 index 692fdfe00a1..00000000000 --- a/doc/user/project/members/img/project_members_filter_v12_6.png +++ /dev/null diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 00474098487..057c2930706 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -37,10 +37,7 @@ From the image above, we can deduce the following things: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6. > - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/4901) in GitLab 13.9. -> - Improvements are [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - Improvements are enabled on GitLab.com. -> - Improvements are recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable improvements](#enable-or-disable-improvements-to-project-member-management). **(FREE SELF)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299954) in GitLab 13.10. The following sections illustrate how you can filter and sort members in a project. To view these options, navigate to your desired project, go to **Members**, and include the noted search terms. @@ -199,27 +196,3 @@ To remove a member from a project: A **Remove member** modal appears. 1. (Optional) Select the **Also unassign this user from related issues and merge requests** checkbox. 1. Click **Remove member**. - -## Enable or disable improvements to project member management **(FREE SELF)** - -Project member management improvements are deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable the improvements. - -To disable them: - -```ruby -# For the instance -Feature.disable(:vue_project_members_list) -# For a single project -Feature.disable(:vue_project_members_list, Project.find(<project id>)) -``` - -To enable them: - -```ruby -# For the instance -Feature.enable(:vue_project_members_list) -# For a single project -Feature.enable(:vue_project_members_list, Project.find(<project id>)) -``` diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 7000988d9bf..8ca403783cb 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -62,4 +62,4 @@ It is possible to prevent projects in a group from [sharing a project with another group](../members/share_project_with_groups.md). This allows for tighter control over project access. -Learn more about [Share with group lock](../../group/index.md#share-with-group-lock). +Learn more about [Share with group lock](../../group/index.md#prevent-a-project-from-being-shared-with-groups). diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 7aa7673366d..5917d67c398 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -18,15 +18,15 @@ This feature is available for merge requests across forked projects that are publicly accessible. When enabled for a merge request, members with merge access to the target -branch of the project will be granted write permissions to the source branch +branch of the project is granted write permissions to the source branch of the merge request. ## Enabling commit edits from upstream members In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/23308), this setting is enabled by default. It can be changed by users with Developer -permissions to the source project. Once enabled, upstream members will also be -able to retry the pipelines and jobs of the merge request: +permissions to the source project. Once enabled, upstream members can +retry the pipelines and jobs of the merge request: 1. While creating or editing a merge request, select the checkbox **Allow commits from members who can merge to the target branch**. @@ -64,7 +64,7 @@ Here's how the process would look like: git checkout -b thedude-awesome-project-update-docs FETCH_HEAD ``` - This will fetch the branch of the forked project and then create a local branch + This fetches the branch of the forked project and then create a local branch based off the fetched branch. 1. Make any changes you want and commit. @@ -74,7 +74,7 @@ Here's how the process would look like: git push git@gitlab.com:thedude/awesome-project.git thedude-awesome-project-update-docs:update-docs ``` - Note the colon (`:`) between the two branches. The above command will push the + Note the colon (`:`) between the two branches. The above command pushes the local branch `thedude-awesome-project-update-docs` to the `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository. diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 36481ac0133..aa43d34cdd9 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts --- diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 6fa2340c7a4..7a869ed071a 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -13,6 +13,9 @@ If your application offers a web interface and you're using [GitLab CI/CD](../../../ci/README.md), you can quickly determine the rendering performance impact of pending code changes in the browser. +NOTE: +You can automate this feature in your applications by using [Auto DevOps](../../../topics/autodevops/index.md). + ## Overview GitLab uses [Sitespeed.io](https://www.sitespeed.io), a free and open source @@ -90,7 +93,7 @@ that you can later download and analyze. This implementation always takes the la Browser Performance artifact available. If [GitLab Pages](../pages/index.md) is enabled, you can view the report directly in your browser. -You can also customize the jobs with environment variables: +You can also customize the jobs with CI/CD 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 `14.1.0`). @@ -115,7 +118,7 @@ performance: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27599) in GitLab 13.0. You can configure the sensitivity of degradation alerts to avoid getting alerts for minor drops in metrics. -This is done by setting the `DEGRADATION_THRESHOLD` variable. In the example below, the alert only shows up +This is done by setting the `DEGRADATION_THRESHOLD` CI/CD variable. In the example below, the alert only shows up if the `Total Score` metric degrades by 5 points or more: ```yaml @@ -186,7 +189,7 @@ GitLab version: - In GitLab 12.4 [a job template was made available](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). - In 13.2 the feature was renamed from `Performance` to `Browser Performance` with -additional template variables. The job name in the template is still `performance` +additional template CI/CD variables. The job name in the template is still `performance` for compatibility reasons, but may be renamed to match in a future iteration. - For 11.5 to 12.3 no template is available and the job has to be defined manually as follows: diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 55dc0bcc41a..42c2547a618 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -22,8 +22,7 @@ Code Quality: [GitLab Code Quality](https://gitlab.com/gitlab-org/ci-cd/codequality) project using [default Code Climate configurations](https://gitlab.com/gitlab-org/ci-cd/codequality/-/tree/master/codeclimate_defaults). - Can make use of a [template](#example-configuration). -- Is available with [Auto - DevOps](../../../topics/autodevops/stages.md#auto-code-quality). +- Is available by using [Auto Code Quality](../../../topics/autodevops/stages.md#auto-code-quality), provided by [Auto DevOps](../../../topics/autodevops/index.md). - Can be extended through [Analysis Plugins](https://docs.codeclimate.com/docs/list-of-engines) or a [custom tool](#implementing-a-custom-tool). ## Code Quality Widget @@ -90,7 +89,7 @@ scans your source code for code quality issues. The report is saved as a that you can later download and analyze. It's also possible to override the URL to the Code Quality image by -setting the `CODE_QUALITY_IMAGE` variable. This is particularly useful if you want +setting the `CODE_QUALITY_IMAGE` CI/CD variable. This is particularly useful if you want to lock in a specific version of Code Quality, or use a fork of it: ```yaml @@ -236,12 +235,12 @@ was chosen as an operational decision by the runner team, instead of exposing `d ### Disabling the code quality job -The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` environment -variable is present. Please refer to the environment variables [documentation](../../../ci/variables/README.md) +The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` CI/CD variable +is present. Please refer to the CI/CD variables [documentation](../../../ci/variables/README.md) to learn more about how to define one. -To disable the `code_quality` job, add `CODE_QUALITY_DISABLED` as a custom environment -variable. This can be done: +To disable the `code_quality` job, add `CODE_QUALITY_DISABLED` as a custom CI/CD variable. +This can be done: - For the whole project, [in the project settings](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui) or [CI/CD configuration](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). @@ -268,7 +267,7 @@ code_quality: - if: '$CI_COMMIT_TAG || $CI_COMMIT_BRANCH' ``` -If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/README.md#workflowrules)) +If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/README.md#workflow)) might look like this example: ```yaml @@ -365,7 +364,7 @@ After the Code Quality job completes: In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/ci-cd/codequality/-/issues/10), it is possible to generate an HTML report file by setting the `REPORT_FORMAT` -variable to `html`. This is useful if you just want to view the report in a more +CI/CD variable to `html`. This is useful if you just want to view the report in a more human-readable format or to publish this artifact on GitLab Pages for even easier reviewing. @@ -509,6 +508,7 @@ This can be due to multiple reasons: nothing is displayed. - The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD setting can cause the Code Quality artifact(s) to expire faster than desired. +- The widgets use the pipeline of the latest commit to the target branch. If commits are made to the default branch that do not run the code quality job, this may cause the Merge Request widget to have no base report for comparison. - If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request. - Large `gl-code-quality-report.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). As a work-around, try removing [properties](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 5cfedc6c9f1..58e80504212 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto description: "How to create Merge Requests in GitLab." @@ -30,11 +30,16 @@ button and start a merge request from there. ## New Merge Request page -On the **New Merge Request** page, start by filling in the title -and description for the merge request. If there are already -commits on the branch, the title is prefilled with the first -line of the first commit message, and the description is -prefilled with any additional lines in the commit message. +On the **New Merge Request** page, start by filling in the title and description +for the merge request. If commits already exist on the branch, GitLab suggests a +merge request title for you: + +- **If a multi-line commit message exists**: GitLab adds the first line of the + first multi-line commit message as the title. Any additional lines in that + commit message become the description. +- **If no multi-line commit message exists**: GitLab adds the branch name as the + title, and leaves the description blank. + The title is the only field that is mandatory in all cases. From there, you can fill it with information (title, description, diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md new file mode 100644 index 00000000000..a030961e219 --- /dev/null +++ b/doc/user/project/merge_requests/drafts.md @@ -0,0 +1,99 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference, concepts +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/work_in_progress_merge_requests.html' +--- + +# Draft merge requests **(FREE)** + +If a merge request isn't ready to merge, potentially because of continued development +or open threads, you can prevent it from being accepted before you +[mark it as ready](#mark-merge-requests-as-ready). Flag it as a draft to disable +the **Merge** button until you remove the **Draft** flag: + + + +## Mark merge requests as drafts + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** is scheduled for removal in GitLab 14.0. +> - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. + +There are several ways to flag a merge request as a draft: + +- **Viewing a merge request**: In the top right corner of the merge request, click **Mark as draft**. +- **Creating or editing a merge request**: Add `[Draft]`, `Draft:` or `(Draft)` to + the beginning of the merge request's title, or click **Start the title with Draft:** + below the **Title** field. +- **Commenting in an existing merge request**: Add the `/draft` + [quick action](../quick_actions.md#issues-merge-requests-and-epics) + in a comment. This quick action is a toggle, and can be repeated to change the status + again. This quick action discards any other text in the comment. +- **Creating a commit**: Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the + beginning of a commit message targeting the merge request's source branch. This + is not a toggle, and adding this text again in a later commit doesn't mark the + merge request as ready. + +WARNING: +Adding `WIP:` to the start of the merge request's title still marks a merge request +as a draft. This feature is scheduled for removal in GitLab 14.0. Use `Draft:` instead. + +## Mark merge requests as ready + +When a merge request is ready to be merged, you can remove the `Draft` flag in several ways: + +- **Viewing a merge request**: In the top right corner of the merge request, click **Mark as ready**. + Users with [Developer or greater permissions](../../permissions.md) + can also scroll to the bottom of the merge request description and click **Mark as ready**: + +  + +- **Editing an existing merge request**: Remove `[Draft]`, `Draft:` or `(Draft)` + from the beginning of the title, or click **Remove the Draft: prefix from the title** + below the **Title** field. +- **Commenting in an existing merge request**: Add the `/draft` + [quick action](../quick_actions.md#issues-merge-requests-and-epics) + in a comment in the merge request. This quick action is a toggle, and can be repeated + to change the status back. This quick action discards any other text in the comment. + +In [GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/15332), +when you mark a merge request as ready, notifications are triggered to +[merge request participants and watchers](../../profile/notifications.md#notifications-on-issues-merge-requests-and-epics). + +## Include or exclude drafts when searching + +When viewing or searching in your project's merge requests list, you can include or exclude +draft merge requests: + +1. In your project, select **Merge Requests** from the left sidebar. +1. In the navigation bar, click **Open**, **Merged**, **Closed**, or **All** to + filter by merge request status. +1. Click the search box to display a list of filters and select **Draft**, or + enter the word `draft`. +1. Select `=`. +1. Select **Yes** to include drafts, or **No** to exclude, and press **Return** + to update the list of merge requests: + +  + +## Pipelines for drafts + +When the [pipelines for merged results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md) +feature is enabled, draft merge requests run +[merge request pipelines](../../../ci/merge_request_pipelines/index.md) only. + +To run pipelines for merged results, you must +[mark the merge request as ready](#mark-merge-requests-as-ready). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index c4a34f9c65c..b1e8d761f5c 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -17,7 +17,7 @@ to accept merge requests without creating merge commits. When the fast-forward merge ([`--ff-only`](https://git-scm.com/docs/git-merge#git-merge---ff-only)) setting -is enabled, no merge commits will be created and all merges are fast-forwarded, +is enabled, no merge commits are created and all merges are fast-forwarded, which means that merging is only allowed if the branch can be fast-forwarded. When a fast-forward merge is not possible, the user is given the option to rebase. @@ -28,19 +28,19 @@ When a fast-forward merge is not possible, the user is given the option to rebas 1. Select the **Fast-forward merge** option 1. Hit **Save changes** for the changes to take effect -Now, when you visit the merge request page, you will be able to accept it +Now, when you visit the merge request page, you can accept it **only if a fast-forward merge is possible**.  If a fast-forward merge is not possible but a conflict free rebase is possible, -a rebase button will be offered. +a rebase button is offered.  If the target branch is ahead of the source branch and a conflict free rebase is not possible, you need to rebase the -source branch locally before you will be able to do a fast-forward merge. +source branch locally before you can do a fast-forward merge.  diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index b1a57d9c3e6..f25228729cf 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference description: "Getting started with Merge Requests." @@ -60,7 +60,7 @@ request's page at the top-right side: - [Close issues automatically](#merge-requests-to-close-issues) when they are merged. - Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option to keep your repository clean. - Enable the [squash commits when merge request is accepted](squash_and_merge.md) option to combine all the commits into one before merging, thus keep a clean commit history in your repository. -- Set the merge request as a [**Draft**](work_in_progress_merge_requests.md) to avoid accidental merges before it is ready. +- Set the merge request as a [**Draft**](drafts.md) to avoid accidental merges before it is ready. After you have created the merge request, you can also: @@ -84,7 +84,7 @@ See also other [features associated to merge requests](reviewing_and_managing_me Choose an assignee to designate someone as the person responsible for the first [review of the merge request](reviewing_and_managing_merge_requests.md). Open the drop down box to search for the user you wish to assign, -and the merge request will be added to their +and the merge request is added to their [assigned merge request list](../../search/index.md#issues-and-merge-requests). #### Multiple assignees **(PREMIUM)** @@ -110,7 +110,7 @@ dropdown menu. It is also possible to manage multiple assignees: - When creating a merge request. -- Using [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). +- Using [quick actions](../quick_actions.md#issues-merge-requests-and-epics). ### Reviewer @@ -122,17 +122,19 @@ Requesting a code review is an important part of contributing code. However, dec your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and reviewers makes it hard for others to determine who's doing what on a merge request. -GitLab Merge Request Reviewers easily allow authors to request a review as well as see the status of the -review. By selecting one or more users from the **Reviewers** field in the merge request's right-hand -sidebar, the assigned reviewers will receive a notification of the request to review the merge request. +The Merge Request Reviewers feature enables you to request a review of your work, and +see the status of the review. Reviewers help distinguish the roles of the users +involved in the merge request. In comparison to an **Assignee**, who is directly +responsible for creating or merging a merge request, a **Reviewer** is a team member +who may only be involved in one aspect of the merge request, such as a peer review. -This makes it easy to determine the relevant roles for the users involved in the merge request, as well as formally requesting a review from a peer. - -To request it, open the **Reviewers** drop-down box to search for the user you wish to get a review from. +To request a review of a merge request, expand the **Reviewers** select box in +the right-hand sidebar. Search for the users you want to request a review from. +When selected, GitLab creates a [to-do list item](../../todos.md) for each reviewer. #### Approval Rule information for Reviewers **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. For this version only, GitLab administrators can opt to [enable it](#enable-or-disable-approval-rule-information). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. When editing the **Reviewers** field in a new or existing merge request, GitLab @@ -162,6 +164,13 @@ the author of the merge request can request a new review from the reviewer: GitLab creates a new [to-do item](../../todos.md) for the reviewer, and sends them a notification email. +#### Approval status + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292936) in GitLab 13.10. + +If a user in the reviewer list has approved the merge request, a green tick symbol is +shown to the right of their name. + ### Merge requests to close issues If the merge request is being created to resolve an issue, you can @@ -198,9 +207,9 @@ is set for deletion, the merge request widget displays the > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. > - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-branch-retargeting-on-merge). +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) on GitLab 13.10. +> - It's recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [disable it](#enable-or-disable-branch-retargeting-on-merge). **(FREE SELF)** In specific circumstances, GitLab can retarget the destination branch of open merge request, if the destination branch merges while the merge request is @@ -221,6 +230,12 @@ GitLab retargets up to four merge requests when their target branch is merged in `master`, so you don't need to perform this operation manually. Merge requests from forks are not retargeted. +The feature today works only one a merge. Clicking the `Remove source branch` button +after the merge request was merged will not automatically retarget merge request. +The feature today works only on merge. Clicking the **Remove source branch** button +after the merge request was merged will not automatically retarget a merge request. +This improvement is [tracked as a follow-up](https://gitlab.com/gitlab-org/gitlab/-/issues/321559). + ## Recommendations and best practices for Merge Requests - When working locally in your branch, add multiple commits and only push when @@ -231,33 +246,6 @@ forks are not retargeted. reviews are faster and your changes are less prone to errors. - Do not use capital letters nor special chars in branch names. -## Enable or disable Approval Rule information **(PREMIUM SELF)** - -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. - -Merge Request Reviewers is under development and ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -# For the instance -Feature.enable(:reviewer_approval_rules) -# For a single project -Feature.enable(:reviewer_approval_rules, Project.find(<project id>)) -``` - -To disable it: - -```ruby -# For the instance -Feature.disable(:reviewer_approval_rules) -# For a single project -Feature.disable(:reviewer_approval_rules, Project.find(<project id>)) -``` - ### Enable or disable branch retargeting on merge **(FREE SELF)** Automatically retargeting merge requests is under development but ready for production use. diff --git a/doc/user/project/merge_requests/img/comment-on-any-diff-line.png b/doc/user/project/merge_requests/img/comment-on-any-diff-line.png Binary files differdeleted file mode 100644 index cff5acb98ef..00000000000 --- a/doc/user/project/merge_requests/img/comment-on-any-diff-line.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/comment-on-any-diff-line_v13_10.png b/doc/user/project/merge_requests/img/comment-on-any-diff-line_v13_10.png Binary files differnew file mode 100644 index 00000000000..a31fea85be9 --- /dev/null +++ b/doc/user/project/merge_requests/img/comment-on-any-diff-line_v13_10.png diff --git a/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_10.png b/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_10.png Binary files differnew file mode 100644 index 00000000000..3bac9f7fee8 --- /dev/null +++ b/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_10.png diff --git a/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_2.png b/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_2.png Binary files differdeleted file mode 100644 index f7968772500..00000000000 --- a/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_2.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/filter_draft_merge_requests_v13_10.png b/doc/user/project/merge_requests/img/filter_draft_merge_requests_v13_10.png Binary files differnew file mode 100644 index 00000000000..4458df987d6 --- /dev/null +++ b/doc/user/project/merge_requests/img/filter_draft_merge_requests_v13_10.png diff --git a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png b/doc/user/project/merge_requests/img/filter_wip_merge_requests.png Binary files differdeleted file mode 100644 index 0989b41e2a4..00000000000 --- a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/multiline-comment-highlighted.png b/doc/user/project/merge_requests/img/multiline-comment-highlighted.png Binary files differdeleted file mode 100644 index 1bdcc37e274..00000000000 --- a/doc/user/project/merge_requests/img/multiline-comment-highlighted.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v12_8.png b/doc/user/project/merge_requests/img/scoped_to_protected_branch_v12_8.png Binary files differdeleted file mode 100644 index 9446ed66c38..00000000000 --- a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v12_8.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png b/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png Binary files differnew file mode 100644 index 00000000000..b1c2e147134 --- /dev/null +++ b/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png diff --git a/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png b/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png Binary files differnew file mode 100644 index 00000000000..c0cc0db600c --- /dev/null +++ b/doc/user/project/merge_requests/img/update_approval_rule_v13_10.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 differdeleted file mode 100644 index af713b48140..00000000000 --- a/doc/user/project/merge_requests/img/update_approval_rule_v13_4.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 8ccf50e48b8..99e0193d496 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -1,16 +1,29 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference --- # Merge requests **(FREE)** -A Merge Request (**MR**) is a _request_ to _merge_ one branch into another. +Whenever you need to merge one branch into another branch with GitLab, you +must create a merge request (MR). -Use merge requests to visualize and collaborate on proposed changes -to source code. +Using merge requests, you can visualize and collaborate on proposed changes to +source code. Merge requests display information about the proposed code changes, +including: + +- A description of the request. +- Code changes and inline code reviews. +- Information about CI/CD pipelines. +- A comment section for discussion threads. +- The list of commits. + +Based on your workflow, after review you can merge a merge request into its +target branch. + +To get started, read the [introduction to merge requests](getting_started.md). ## Use cases @@ -36,21 +49,9 @@ B. Consider you're a web developer writing a webpage for your company's website: 1. Your changes are previewed with [Review Apps](../../../ci/review_apps/index.md) 1. You request your web designers for their implementation 1. You request the [approval](merge_request_approvals.md) from your manager **(STARTER)** -1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/) +1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/) 1. Your production team [cherry picks](cherry_pick_changes.md) the merge commit into production -## Overview - -Merge requests (aka "MRs") display a great deal of information about the changes proposed. -The body of an MR contains its description, along with its widget (displaying information -about CI/CD pipelines, when present), followed by the discussion threads of the people -collaborating with that MR. - -MRs also contain navigation tabs from which you can see the discussion happening on the thread, -the list of commits, the list of pipelines and jobs, the code changes, and inline code reviews. - -To get started, read the [introduction to merge requests](getting_started.md). - ## Merge request navigation tabs at the top > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33813) in GitLab 12.6. This positioning is experimental. diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 9154897d42d..e8062fadcfe 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -104,8 +104,8 @@ An example configuration workflow: 1. Set up GitLab Runner to run Docker containers, like the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). -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: +1. Configure the default Load Performance Testing CI/CD job in your `.gitlab-ci.yml` file. + You need to include the template and configure it with CI/CD variables: ```yaml include: @@ -153,7 +153,7 @@ 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 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` +as a job artifact to be shared, then use a custom CI/CD 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}`)``. diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 1fcc09a9d8a..3d3e04842f8 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -79,7 +79,8 @@ An individual user can be added as an approver for a project if they are a membe - The project's immediate parent group. - A group that has access to the project via a [share](../members/share_project_with_groups.md). -A group of users can also be added as approvers. In the future, group approvers may be +A group of users can also be added as approvers, though they only count as approvers if +they have direct membership to the group. In the future, group approvers may be [restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048). If a user is added as an individual approver and is also part of a group approver, @@ -138,17 +139,17 @@ 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 +1. [Create a new group](../../group/index.md#create-a-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. +1. Select **Add approval rule** or **Update approval rule**. +1. [Add the group](../../group/index.md#create-a-group) to the permission list. - + #### Adding / editing a default approval rule @@ -239,7 +240,7 @@ the **Target branch** dropdown. Alternatively, you can select a very specific protected branch from the **Target branch** dropdown: - + To enable this configuration, see [Code Owner’s approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 646d77391a3..2d7ba853258 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -40,8 +40,7 @@ require changes to `awesome-lib`, and so necessitate two merge requests. Merging the `awesome-project` merge request before the `awesome-lib` one would break the `master`branch. -The `awesome-project` merge request could be [marked as -**Draft**](work_in_progress_merge_requests.md), +The `awesome-project` merge request could be [marked as **Draft**](drafts.md), and the reason for the draft stated included in the comments. However, this requires the state of the `awesome-lib` merge request to be manually tracked, and doesn't scale well if the `awesome-project` merge request @@ -85,7 +84,7 @@ merge request widget:  Until all dependencies have, themselves, been merged, the **Merge** -button will be disabled for the dependent merge request. In +button is disabled for the dependent merge request. In particular, note that **closed merge requests** still prevent their dependents from being merged - it is impossible to automatically determine whether the dependency expressed by a closed merge request diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index d33a8e40aac..58f2c310375 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -94,7 +94,7 @@ merge-request-pipeline-job: ``` You should avoid configuration like this, and only use branch (`push`) pipelines -or merge request pipelines, when possible. See [`rules` documentation](../../../ci/yaml/README.md#prevent-duplicate-pipelines) +or merge request pipelines, when possible. See [`rules` documentation](../../../ci/yaml/README.md#avoid-duplicate-pipelines) for details on avoiding two pipelines for a single merge request. ### Skipped pipelines diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index a53b5032e1d..4d5d89d6508 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index d5d0578c07c..a798f2c9b85 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -13,27 +13,26 @@ by clicking the **Revert** button in merge requests and commit details. ## Reverting a merge request NOTE: -The **Revert** button will only be available for merge requests +The **Revert** button is available only for merge requests created in GitLab 8.5 and later. However, you can still revert a merge request by reverting the merge commit from the list of Commits page. NOTE: -The **Revert** button will only be shown for projects that use the +The **Revert** button is shown only for projects that use the merge method "Merge Commit", which can be set under the project's **Settings > General > Merge request**. [Fast-forward commits](fast_forward_merge.md) -can not be reverted via the MR view. +can not be reverted by using the merge request view. -After the Merge Request has been merged, a **Revert** button will be available +After the merge request has been merged, use the **Revert** button to revert the changes introduced by that merge request. - + -After you click that button, a modal will appear where you can choose to +After you click that button, a modal appears where you can choose to revert the changes directly into the selected branch or you can opt to create a new merge request with the revert changes. -After the merge request has been reverted, the **Revert** button will not be -available anymore. +After the merge request has been reverted, the **Revert** button is no longer available. ## Reverting a commit @@ -45,14 +44,13 @@ Similar to reverting a merge request, you can opt to revert the changes directly into the target branch or create a new merge request to revert the changes. -After the commit has been reverted, the **Revert** button will not be available -anymore. +After a commit is reverted, the **Revert** button is no longer available. -Please note that when reverting merge commits, the mainline will always be the -first parent. If you want to use a different mainline then you need to do that +When reverting merge commits, the mainline is always the +first parent. If you want to use a different mainline, you need to do that from the command line. -Here is a quick example to revert a merge commit using the second parent as the +Here's an example to revert a merge commit using the second parent as the mainline: ```shell 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 94f48fa544f..406a79217d0 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 @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference --- @@ -187,27 +187,31 @@ Feature.disable(:local_file_reviews) > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. In a merge request, you can leave comments in any part of the file being changed. -In the Merge Request Diff UI, click the **{comment}** **comment** icon in the gutter -to expand the diff lines and leave a comment, just as you would for a changed line. +In the Merge Request Diff UI, you can: - +- **Comment on a single line**: Click the **{comment}** **comment** icon in the + gutter to expand the diff lines and display a comment box. +- [**Comment on multiple lines**](#commenting-on-multiple-lines). ### Commenting on multiple lines > - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) click-and-drag features in GitLab 13.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. -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. -The last line is the line that the comment icon was initially clicked on. +When commenting on a diff, you can select which lines of code your comment refers +to by either: -New comments default to single line comments by having the first and last lines -the same. Selecting a different starting line turns this into a multiline comment. + - +- Clicking and dragging the **{comment}** **comment** icon in the gutter to highlight + lines in the diff. GitLab expands the diff lines and displays a comment box. +- After starting a comment by clicking the **{comment}** **comment** icon in the + gutter, select the first line number your comment refers to in the **Commenting on lines** + select box. New comments default to single-line comments, unless you select + a different starting line. -Once a multiline comment is saved the lines of code pertaining to that comment are listed directly -above it. +Multiline comments display the comment's line numbers above the body of the comment:  diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 1b99b1b5c44..f500c18a32e 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -31,7 +31,7 @@ NOTE: The squashed commit in this example is followed by a merge commit, because the merge method for this repository uses a merge commit. You can disable merge commits in **Project Settings > General > Merge requests > Merge method > Fast-forward merge**. -The squashed commit's commit message will be either: +The squashed commit's commit message is either: - Taken from the first multi-line commit message in the merge. - The merge request's title if no multi-line commit message is found. @@ -60,7 +60,7 @@ This way, the history of your base branch remains clean with meaningful commit messages and: - It's simpler to [revert](revert_changes.md) if necessary. -- The merged branch will retain the full commit history. +- The merged branch retains the full commit history. ## Enabling squash for a merge request @@ -113,18 +113,18 @@ squashing can itself be considered equivalent to rebasing. 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**. -You will find the following options to choose, which will affect existing and new merge requests +You can choose from these options, which affect existing and new merge requests submitted to your project: - **Do not allow**: users cannot use Squash and Merge to squash all the commits immediately before - merging. The checkbox to enable or disable it will be unchecked and hidden from the users. -- **Allow**: users will have the option to enable Squash and Merge on a merge request basis. - The checkbox will be unchecked (disabled) by default, but and the user is allowed to enable it. -- **Encourage**: users will have the option to enable Squash and Merge on a merge request basis. - The checkbox will be checked (enabled) by default to encourage its use, but the user is allowed to + merging. The checkbox to enable or disable it is unchecked and hidden from the users. +- **Allow**: users can enable Squash and Merge on a merge request basis. + The checkbox is unchecked (disabled) by default, but and the user is allowed to enable it. +- **Encourage**: users can enable Squash and Merge on a merge request basis. + The checkbox is checked (enabled) by default to encourage its use, but the user is allowed to disable it. -- **Require**: Squash and Merge is enabled for all merge requests, so it will always be performed. - The checkbox to enable or disable it will be checked and hidden from the users. +- **Require**: Squash and Merge is enabled for all merge requests, so it is always performed. + The checkbox to enable or disable it is checked and hidden from the users. The Squash and Merge checkbox is displayed when you create a merge request and when you edit the description of an existing one, except when Squash Commit Options is set to **Do not allow** or **Require**. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index e60f2f712d3..02b557e22b9 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -146,7 +146,7 @@ coverage-jdk11: # The `visualize` stage does not exist by default. # Please define it first, or chose an existing stage like `deploy`. stage: visualize - image: haynes/jacoco2cobertura:1.0.4 + image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.7 script: # convert report from jacoco to cobertura - 'python /opt/cover2cover.py target/site/jacoco/jacoco.xml src/main/java > target/site/cobertura.xml' @@ -186,7 +186,7 @@ coverage-jdk11: # The `visualize` stage does not exist by default. # Please define it first, or chose an existing stage like `deploy`. stage: visualize - image: haynes/jacoco2cobertura:1.0.4 + image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.7 script: # convert report from jacoco to cobertura - 'python /opt/cover2cover.py build/jacoco/jacoco.xml src/main/java > build/cobertura.xml' @@ -219,3 +219,32 @@ run tests: reports: cobertura: coverage.xml ``` + +### C/C++ example + +The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for C/C++ with +`gcc` or `g++` as the compiler uses [`gcovr`](https://gcovr.com/en/stable/) to generate the coverage +output file in Cobertura XML format. + +This example assumes: + +- That the `Makefile` is created by `cmake` in the `build` directory, + within another job in a previous stage. + (If you use `automake` to generate the `Makefile`, + then you need to call `make check` instead of `make test`.) +- `cmake` (or `automake`) has set the compiler option `--coverage`. + +```yaml +run tests: + stage: test + script: + - cd build + - make test + - gcovr --xml-pretty --exclude-unreachable-branches --print-summary -o coverage.xml --root ${CI_PROJECT_DIR} + coverage: /^\s*lines:\s*\d+.\d+\%/ + artifacts: + name: ${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}-${CI_COMMIT_SHA} + expire_in: 2 days + reports: + cobertura: build/coverage.xml +``` diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 8f3ce9186f1..2c77957c98d 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -64,7 +64,7 @@ In GitLab 12.10, we added a comparison mode, which shows a diff calculated by simulating how it would look like once merged - a more accurate representation of the changes rather than using the base of the two branches. The new mode is available from the comparison target drop down -by selecting **master (HEAD)**. In GitLab 13.9, it +by selecting **master (HEAD)**. In GitLab 13.9, it [replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the old default comparison. For technical details, additional information is available in the [developer documentation](../../../development/diffs.md#merge-request-diffs-against-the-head-of-the-target-branch). diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index 43ab03114fa..4b854da116e 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -1,78 +1,8 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, concepts +redirect_to: 'drafts.md' --- -# Draft merge requests **(FREE)** +This document was moved to [another location](drafts.md). -If a merge request is not yet ready to be merged, perhaps due to continued development -or open threads, you can prevent it from being accepted before it's ready by flagging -it as a **Draft**. This disables the **Merge** button, preventing it from -being merged. It stays disabled until the **Draft** flag has been removed. - - - -When [pipelines for merged results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md) -is enabled, draft merge requests run [merge request pipelines](../../../ci/merge_request_pipelines/index.md) -only. - -To run pipelines for merged results, you must [remove the draft status](#removing-the-draft-flag-from-a-merge-request). - -## Adding the "Draft" flag to a merge request - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** is scheduled for removal in GitLab 14.0. -> - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. - -There are several ways to flag a merge request as a Draft: - -- Click the **Mark as draft** button on the top-right corner of the merge request's page. -- Add `[Draft]`, `Draft:` or `(Draft)` to the start of the merge request's title. Clicking on - **Start the title with Draft:**, under the title box, when editing the merge request's - description has the same effect. -- **Deprecated** Add `[WIP]` or `WIP:` to the start of the merge request's title. - **WIP** still works but was deprecated in favor of **Draft**. It is scheduled for removal in the next major version (GitLab 14.0). -- Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) - in a comment in the merge request. This is a toggle, and can be repeated - to change the status back. Note that any other text in the comment is discarded. -- Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the beginning of a commit message targeting the - merge request's source branch. This is not a toggle, and doing it again in another - commit has no effect. - -## Removing the "Draft" flag from a merge request - -Similar to above, when a Merge Request is ready to be merged, you can remove the -`Draft` flag in several ways: - -- Click the **Mark as ready** button on the top-right corner of the merge request's page. -- Remove `[Draft]`, `Draft:` or `(Draft)` from the start of the merge request's title. Clicking on - **Remove the Draft: prefix from the title**, under the title box, when editing the merge - request's description, has the same effect. -- Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) - in a comment in the merge request. This is a toggle, and can be repeated - to change the status back. Note that any other text in the comment is discarded. -- Click on the **Resolve Draft status** button near the bottom of the merge request description, - next to the **Merge** button (see [image above](#draft-merge-requests)). - Must have at least Developer level permissions on the project for the button to - be visible. - -## Including/excluding WIP merge requests when searching - -When viewing/searching the merge requests list, you can choose to include or exclude -WIP merge requests. Add a **WIP** filter in the search box, and choose **Yes** -to include, or **No** to exclude. - - - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +<!-- This redirect file can be deleted after <2021-05-19>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md deleted file mode 100644 index 2985e5da2ab..00000000000 --- a/doc/user/project/milestones/burndown_charts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'burndown_and_burnup_charts.md' ---- - -This document was moved to [another location](burndown_and_burnup_charts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index e0d5e8be535..30dd337d9d8 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -41,7 +41,7 @@ configuration for the Pages site to generate properly. If everything is configured correctly, the site can take approximately 30 minutes to deploy. -You can watch the pipeline run by navigating to **CI / CD > Pipelines**. +You can watch the pipeline run by navigating to **CI/CD > Pipelines**. When the pipeline is finished, go to **Settings > Pages** to find the link to your Pages website. 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 3f2df634e3a..8368b38bc80 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -152,7 +152,7 @@ pages: ``` Now save and commit the `.gitlab-ci.yml` file. You can watch the pipeline run -by going to **CI / CD > Pipelines**. +by going to **CI/CD > Pipelines**. When it succeeds, go to **Settings > Pages** to view the URL where your site is now available. @@ -396,7 +396,7 @@ but also pushes with **continuous tests** to feature-branches, For more information, see the following blog posts. - [Use GitLab CI/CD `environments` to deploy your - web app to staging and production](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/). + web app to staging and production](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). - Learn [how to run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/). - Learn [how to pull specific directories from different projects](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 6eb06972945..2a0e1207bf5 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -46,9 +46,9 @@ To create a GitLab Pages website: | Document | Description | | -------- | ----------- | -| [Fork a sample project](getting_started/pages_forked_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | | [Use a new project template](getting_started/pages_new_project_template.md) | Create a new project with Pages already configured by using a new project template. | | [Use a `.gitlab-ci.yml` template](getting_started/pages_ci_cd_template.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. | +| [Fork a sample project](getting_started/pages_forked_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | | [Create a `gitlab-ci.yml` file from scratch](getting_started/pages_from_scratch.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | To update a GitLab Pages website: @@ -116,7 +116,7 @@ to use and adapt to your own needs: - [Posting to your GitLab Pages blog from iOS](https://about.gitlab.com/blog/2016/08/19/posting-to-your-gitlab-pages-blog-from-ios/). - [GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/). -- [GitLab CI: Deployment & environments](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/). +- [GitLab CI: Deployment & environments](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). - [Building a new GitLab docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/). - [Publish code coverage reports with GitLab Pages](https://about.gitlab.com/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/). diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 4629c87f41e..aef96ff12c9 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -35,7 +35,7 @@ See the [Changelog](#changelog) section for changes over time. ## Configuring protected branches To protect a branch, you need to have at least Maintainer permission level. -The `master` branch is protected by default. +The default branch for your repository is protected by default. 1. In your project, go to **Settings > Repository**. 1. Scroll to find the **Protected branches** section. @@ -177,6 +177,41 @@ Deleting a protected branch is allowed only by using the web interface; not from This means that you can't accidentally delete a protected branch from your command line or a Git client application. +## Allow force push on protected branches **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-allow-force-push-on-protected-branches). + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can allow force pushes to protected branches by either setting **Allow force push** +when you protect a new branch, or by configuring an already-protected branch. + +To protect a new branch and enable Force push: + +1. Navigate to your project's **Settings > Repository**. +1. Expand **Protected branches**, and scroll to **Protect a branch**. +  +1. Select a **Branch** or wildcard you'd like to protect. +1. Select the user levels **Allowed to merge** and **Allowed to push**. +1. To allow all users with push access to force push, toggle the **Allow force push** slider. +1. To reject code pushes that change files listed in the `CODEOWNERS` file, toggle + **Require approval from code owners**. +1. Click **Protect**. + +To enable force pushes on branches already protected: + +1. Navigate to your project's **Settings > Repository**. +1. Expand **Protected branches** and scroll to **Protected branch**. +  +1. Toggle the **Allow force push** slider for the chosen branch. + +When enabled, members who are allowed to push to this branch can also force push. + ## Protected branches approval by Code Owners **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab Premium 12.4. @@ -193,14 +228,14 @@ To protect a new branch and enable Code Owner's approval: 1. Scroll down to **Protect a branch**, select a **Branch** or wildcard you'd like to protect, select who's **Allowed to merge** and **Allowed to push**, and toggle the **Require approval from code owners** slider. 1. Click **Protect**. - + To enable Code Owner's approval to branches already protected: 1. Navigate to your project's **Settings > Repository** and expand **Protected branches**. 1. Scroll down to **Protected branch** and toggle the **Code owner approval** slider for the chosen branch. - + When enabled, all merge requests targeting these branches require approval by a Code Owner per matched rule before they can be merged. @@ -216,6 +251,25 @@ run CI/CD pipelines and execute actions on jobs that are related to those branch See [Security on protected branches](../../ci/pipelines/index.md#pipeline-security-on-protected-branches) for details about the pipelines security model. +## Enable or disable allow force push on protected branches **(FREE SELF)** + +Allow force push on protected branches is under development and not ready for +production use. It is deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:allow_force_push_to_protected_branches) +``` + +To disable it: + +```ruby +Feature.disable(:allow_force_push_to_protected_branches) +``` + ## Changelog - **13.5**: [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769). diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index f94a4075363..c557c7718c9 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -34,12 +34,12 @@ git push -o <push_option> ## Push options for GitLab CI/CD -You can use push options to skip a CI/CD pipeline, or pass environment variables. +You can use push options to skip a CI/CD pipeline, or pass CI/CD variables. | Push option | Description | Introduced in version | | ------------------------------ | ------------------------------------------------------------------------------------------- |---------------------- | | `ci.skip` | Do not create a CI pipeline for the latest push. | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | -| `ci.variable="<name>=<value>"` | Provide [environment variables](../../ci/variables/README.md) to be used in a CI pipeline, if one is created due to the push. | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | +| `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/README.md) to be used in a CI pipeline, if one is created due to the push. | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | An example of using `ci.skip`: @@ -47,7 +47,7 @@ An example of using `ci.skip`: git push -o ci.skip ``` -An example of passing some environment variables for a pipeline: +An example of passing some CI/CD variables for a pipeline: ```shell git push -o ci.variable="MAX_RETRIES=10" -o ci.variable="MAX_TIME=600" @@ -66,7 +66,7 @@ time as pushing changes: | `merge_request.remove_source_branch` | Set the merge request to remove the source branch when it's merged. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | | `merge_request.title="<title>"` | Set the title of the merge request. Ex: `git push -o merge_request.title="The title I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | | `merge_request.description="<description>"` | Set the description of the merge request. Ex: `git push -o merge_request.description="The description I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | -| `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it will be created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | +| `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it is created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | | `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | If you use a push option that requires text with spaces in it, you need to enclose it @@ -108,7 +108,7 @@ option](#push-options-for-merge-requests): git config --global alias.mwps "push -o merge_request.create -o merge_request.target=master -o merge_request.merge_when_pipeline_succeeds" ``` -Then to quickly push a local branch that will target master and merge when the +Then to quickly push a local branch that targets the default branch and merges when the pipeline succeeds: ```shell diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index ac65fabd6a7..284deabb33c 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Quick Actions +# GitLab quick actions **(FREE)** > - Introduced in [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26672): > once an action is executed, an alert appears when a quick action is successfully applied. @@ -15,114 +15,113 @@ info: To determine the technical writer assigned to the Stage/Group associated w > `/` into a description or comment field, all available quick actions are displayed in a scrollable list. > - The rebase quick action was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49800) in GitLab 13.8. -Quick actions are textual shortcuts for common actions on issues, epics, merge requests, -and commits that are usually done by clicking buttons or dropdowns in the GitLab UI. -You can enter these commands in the description or in comments of issues, epics, merge requests, and commits. -Each command should be on a separate line in order to be properly detected and executed. - -## Quick Actions for issues, merge requests and epics - -The following quick actions are applicable to descriptions, discussions and threads in: - -- Issues -- Merge requests -- Epics **(PREMIUM)** - -| Command | Issue | Merge request | Epic | Action | -| :------------------------------------ | :---- | :------------ | :--- | :------------------------------------------------------------------------------------------------------------------------------ | -| `/approve` | | ✓ | | Approve the merge request. **(STARTER)** | -| `/assign @user` | ✓ | ✓ | | Assign one user. | -| `/assign @user1 @user2` | ✓ | ✓ | | Assign multiple users. **(STARTER)** | -| `/assign me` | ✓ | ✓ | | Assign yourself. | -| `/assign_reviewer @user` or `/reviewer @user` or `/request_review @user` | | ✓ | | Assign one user as a reviewer. | -| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | | ✓ | | Assign multiple users as reviewers. **(STARTER)** | -| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | | ✓ | | Assign yourself as a reviewer. | -| `/award :emoji:` | ✓ | ✓ | ✓ | Toggle emoji award. | -| `/child_epic <epic>` | | | ✓ | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). **(ULTIMATE)** | -| `/clear_weight` | ✓ | | | Clear weight. **(STARTER)** | -| `/clone <path/to/project> [--with_notes]`| ✓ | | | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. | -| `/close` | ✓ | ✓ | ✓ | Close. | -| `/confidential` | ✓ | | | Make confidential. | -| `/copy_metadata <!merge_request>` | ✓ | ✓ | | Copy labels and milestone from another merge request in the project. | -| `/copy_metadata <#issue>` | ✓ | ✓ | | Copy labels and milestone from another issue in the project. | -| `/create_merge_request <branch name>` | ✓ | | | Create a new merge request starting from the current issue. | -| `/done` | ✓ | ✓ | ✓ | Mark to do as done. | -| `/draft` | | ✓ | | Toggle the draft status. | -| `/due <date>` | ✓ | | | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | -| `/duplicate <#issue>` | ✓ | | | Close this issue and mark as a duplicate of another issue. **(FREE)** Also, mark both as related. **(STARTER)** | -| `/epic <epic>` | ✓ | | | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. **(PREMIUM)** | -| `/estimate <<W>w <DD>d <hh>h <mm>m>` | ✓ | ✓ | | Set time estimate. For example, `/estimate 1w 3d 2h 14m`. | -| `/iteration *iteration:"iteration name"` | ✓ | | | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). **(STARTER)** | -| `/label ~label1 ~label2` | ✓ | ✓ | ✓ | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | -| `/lock` | ✓ | ✓ | | Lock the discussions. | -| `/merge` | | ✓ | | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), adding to a [Merge Train](../../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md), etc. | -| `/milestone %milestone` | ✓ | ✓ | | Set milestone. | -| `/move <path/to/project>` | ✓ | | | Move this issue to another project. | -| `/parent_epic <epic>` | | | ✓ | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). **(ULTIMATE)** | -| `/promote` | ✓ | | | Promote issue to epic. **(PREMIUM)** | -| `/publish` | ✓ | | | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) **(ULTIMATE)** | -| `/reassign @user1 @user2` | ✓ | ✓ | | Replace current assignees with those specified. **(STARTER)** | -| `/rebase` | | ✓ | | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | -| `/reassign_reviewer @user1 @user2` | | ✓ | | Replace current reviewers with those specified. **(STARTER)** | -| `/relabel ~label1 ~label2` | ✓ | ✓ | ✓ | Replace current labels with those specified. | -| `/relate #issue1 #issue2` | ✓ | | | Mark issues as related. **(STARTER)** | -| `/remove_child_epic <epic>` | | | ✓ | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). **(ULTIMATE)** | -| `/remove_due_date` | ✓ | | | Remove due date. | -| `/remove_epic` | ✓ | | | Remove from epic. **(PREMIUM)** | -| `/remove_estimate` | ✓ | ✓ | | Remove time estimate. | -| `/remove_iteration` | ✓ | | | Remove iteration ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)) **(STARTER)** | -| `/remove_milestone` | ✓ | ✓ | | Remove milestone. | -| `/remove_parent_epic` | | | ✓ | Remove parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). **(ULTIMATE)** | -| `/remove_time_spent` | ✓ | ✓ | | Remove time spent. | -| `/remove_zoom` | ✓ | | | Remove Zoom meeting from this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | -| `/reopen` | ✓ | ✓ | ✓ | Reopen. | -| `/shrug <comment>` | ✓ | ✓ | ✓ | Append the comment with `¯\＿(ツ)＿/¯`. | -| `/spend <time(-<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | ✓ | ✓ | | Subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend time(-1h 30m)` or `/spend time(-1h 30m) date(2018-08-26)`. | -| `/spend <time(<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | ✓ | ✓ | | Add spent time. Optionally, specify the date that time was spent on. For example, `/spend time(1h 30m)` or `/spend time(1h 30m) date(2018-08-26)`. | -| `/submit_review` | | ✓ | | Submit a pending review ([introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/8041)). **(PREMIUM)** | -| `/subscribe` | ✓ | ✓ | ✓ | Subscribe to notifications. | -| `/tableflip <comment>` | ✓ | ✓ | ✓ | Append the comment with `(╯°□°)╯︵ ┻━┻`. | -| `/target_branch <local branch name>` | | ✓ | | Set target branch. | -| `/title <new title>` | ✓ | ✓ | ✓ | Change title. | -| `/todo` | ✓ | ✓ | ✓ | Add a to-do item. | -| `/unassign @user1 @user2` | ✓ | ✓ | | Remove specific assignees. **(STARTER)** | -| `/unassign` | | ✓ | | Remove all assignees. | -| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | | ✓ | | Remove specific reviewers. **(STARTER)** | -| `/unassign_reviewer` or `/remove_reviewer` | | ✓ | | Remove all reviewers. | -| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | ✓ | ✓ | ✓ | Remove specified labels. | -| `/unlabel` or `/remove_label` | ✓ | ✓ | ✓ | Remove all labels. | -| `/unlock` | ✓ | ✓ | | Unlock the discussions. | -| `/unsubscribe` | ✓ | ✓ | ✓ | Unsubscribe from notifications. | -| `/weight <value>` | ✓ | | | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. **(STARTER)** | -| `/wip` | | ✓ | | Toggle the draft status. | -| `/zoom <Zoom URL>` | ✓ | | | Add Zoom meeting to this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | - -## Autocomplete characters - -Many quick actions require a parameter, for example: username, milestone, and -label. [Autocomplete characters](autocomplete_characters.md) can make it easier -to enter a parameter, compared to selecting items from a list. - -## Quick actions parameters - -The easiest way to set parameters for quick actions is to use autocomplete. If -you manually enter a parameter, it must be enclosed in double quotation marks +Quick actions are text-based shortcuts for common actions that are usually done +by selecting buttons or dropdowns in the GitLab user interface. You can enter +these commands in the descriptions or comments of issues, epics, merge requests, +and commits. + +Be sure to enter each quick action on a separate line to allow GitLab to +properly detect and execute the commands. + +## Parameters + +Many quick actions require a parameter. For example, the `/assign` quick action +requires a username. GitLab uses [autocomplete characters](autocomplete_characters.md) +with quick actions to help users enter parameters, by providing a list of +available values. + +If you manually enter a parameter, it must be enclosed in double quotation marks (`"`), unless it contains only these characters: -1. ASCII letters. -1. Numerals (0-9). -1. Underscore (`_`), hyphen (`-`), question mark (`?`), dot (`.`), or ampersand (`&`). +- ASCII letters +- Numbers (0-9) +- Underscore (`_`), hyphen (`-`), question mark (`?`), dot (`.`), or ampersand (`&`) -Parameters are also case-sensitive. Autocomplete handles this, and the insertion +Parameters are case-sensitive. Autocomplete handles this, and the insertion of quotation marks, automatically. -## Quick actions for commit messages +## Issues, merge requests, and epics + +The following quick actions are applicable to descriptions, discussions, and +threads. Some quick actions might not be available to all subscription tiers. + +| Command | Issue | Merge request | Epic | Action | +|:--------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| +| `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. | +| `/assign @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one user. | +| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign multiple users. | +| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. | +| `/assign_reviewer @user` or `/reviewer @user` or `/request_review @user` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one user as a reviewer. | +| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign multiple users as reviewers. | +| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. | +| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle emoji award. | +| `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | +| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | +| `/clone <path/to/project> [--with_notes]`| **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. | +| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | +| `/confidential` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Make confidential. | +| `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. | +| `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. | +| `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | +| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to do as done. | +| `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Toggle the draft status. | +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | +| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue and mark as a duplicate of another issue. **(FREE)** Also, mark both as related. | +| `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | +| `/estimate <<W>w <DD>d <hh>h <mm>m>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1w 3d 2h 14m`. | +| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants`. | +| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | +| `/label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | +| `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. | +| `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). | +| `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. | +| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. | +| `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | +| `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | +| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) | +| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | +| `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | +| `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. | +| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | +| `/relate #issue1 #issue2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark issues as related. | +| `/remove_child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | +| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove due date. | +| `/remove_epic` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove from epic. | +| `/remove_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. | +| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | +| `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. | +| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | +| `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. | +| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | +| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | +| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | +| `/spend <time(-<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend time(-1h 30m)` or `/spend time(-1h 30m) date(2018-08-26)`. | +| `/spend <time(<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add spent time. Optionally, specify the date that time was spent on. For example, `/spend time(1h 30m)` or `/spend time(1h 30m) date(2018-08-26)`. | +| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/8041)). | +| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. | +| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | +| `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | +| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | +| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. | +| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | +| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | +| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. | +| `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. | +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | +| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | +| `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. | +| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | +| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | +| `/wip` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Toggle the draft status. | +| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add Zoom meeting to this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | + +## Commit messages The following quick actions are applicable for commit messages: | Command | Action | -| :---------------------- | :---------------------------------------- | -| `/tag v1.2.3 <message>` | Tags this commit with an optional message | +|:----------------------- |:------------------------------------------| +| `/tag v1.2.3 <message>` | Tags the commit with an optional message. | <!-- ## Troubleshooting diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index b5751797870..7348e17a017 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -66,14 +66,11 @@ To create a new release through the GitLab UI: 1. Navigate to **Project overview > Releases** and click the **New release** button. -1. In the [**Tag name**](#tag-name) box, enter a name. - - Creating a release based on an existing tag using the user - interface is not yet supported. However, this is possible using the - [Releases API](../../../api/releases/index.md#create-a-release). - -1. In the **Create from** list, select a branch, tag, or commit SHA to use when - creating the new tag. +1. Open the [**Tag name**](#tag-name) dropdown. Select an existing tag or type + in a new tag name. Selecting an existing tag that is already associated with + a release will result in a validation error. +1. If creating a new tag, open the **Create from** dropdown. Select a + branch, tag, or commit SHA to use when creating the new tag. 1. Optionally, fill out any additional information about the release, such as its [title](#title), [milestones](#associate-milestones-with-a-release), [release notes](#release-notes-description), or [assets links](#links). @@ -214,7 +211,7 @@ To set a deploy freeze window in the UI, complete these steps: 1. Sign in to GitLab as a user with project Maintainer [permissions](../../permissions.md). 1. Navigate to **Project overview**. -1. In the left navigation menu, navigate to **Settings > CI / CD**. +1. In the left navigation menu, navigate to **Settings > CI/CD**. 1. Scroll to **Deploy freezes**. 1. Click **Expand** to see the deploy freeze table. 1. Click **Add deploy freeze** to open the deploy freeze modal. @@ -475,7 +472,7 @@ terminal. Read the [Release CLI documentation](https://gitlab.com/gitlab-org/release-cli/-/blob/master/docs/index.md) for details. -## Release Metrics **(PREMIUM)** +## Release Metrics **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259703) in GitLab Premium 13.9. diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box.png b/doc/user/project/repository/branches/img/branch_filter_search_box.png Binary files differdeleted file mode 100644 index 5dc300cf24e..00000000000 --- a/doc/user/project/repository/branches/img/branch_filter_search_box.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png Binary files differnew file mode 100644 index 00000000000..da7d5268b3b --- /dev/null +++ b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png diff --git a/doc/user/project/repository/branches/img/compare_branches.png b/doc/user/project/repository/branches/img/compare_branches.png Binary files differdeleted file mode 100644 index e6f88da4989..00000000000 --- a/doc/user/project/repository/branches/img/compare_branches.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/compare_branches_v13_10.png b/doc/user/project/repository/branches/img/compare_branches_v13_10.png Binary files differnew file mode 100644 index 00000000000..2b9a5751938 --- /dev/null +++ b/doc/user/project/repository/branches/img/compare_branches_v13_10.png diff --git a/doc/user/project/repository/branches/img/repository_filter_search_box_v13_10.png b/doc/user/project/repository/branches/img/repository_filter_search_box_v13_10.png Binary files differnew file mode 100644 index 00000000000..fdda3858c3b --- /dev/null +++ b/doc/user/project/repository/branches/img/repository_filter_search_box_v13_10.png diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 4d0cf28593d..d049b2108ee 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -64,7 +64,7 @@ against accidental deletion and forced pushes. 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 -else. This way, every new project created from then on will start from the custom branch name rather than `master`. To do so: +else. This way, every new project created from then on starts from the custom branch name rather than `master`. To do so: 1. Go to the **Admin Area > Settings > Repository** and expand **Default initial branch name**. @@ -96,10 +96,11 @@ To compare branches in a repository: 1. Navigate to your project's repository. 1. Select **Repository > Compare** in the sidebar. -1. Select branches to compare using the [branch filter search box](#branch-filter-search-box) +1. Select the target repository to compare with the [repository filter search box](#repository-filter-search-box). +1. Select branches to compare using the [branch filter search box](#branch-filter-search-box). 1. Click **Compare** to view the changes inline: - +  ## Delete merged branches @@ -108,17 +109,30 @@ To compare branches in a repository:  This feature allows merged branches to be deleted in bulk. Only branches that -have been merged and [are not protected](../../protected_branches.md) will be deleted as part of +have been merged and [are not protected](../../protected_branches.md) are deleted as part of this operation. It's particularly useful to clean up old branches that were not deleted automatically when a merge request was merged. +## Repository filter search box + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52967) in GitLab 13.10. + +This feature allows you to search and select a repository quickly when [comparing branches](#compare). + + + +Search results appear in the following order: + +- Repositories with names exactly matching the search terms. +- Other repositories with names that include search terms, sorted alphabetically. + ## Branch filter search box > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22166) in GitLab 11.5. - + This feature allows you to search and select branches quickly. Search results appear in the following order: @@ -127,8 +141,8 @@ This feature allows you to search and select branches quickly. Search results ap Sometimes when you have hundreds of branches you may want a more flexible matching pattern. In such cases you can use the following: -- `^feature` will only match branch names that begin with 'feature'. -- `feature$` will only match branch names that end with 'feature'. +- `^feature` matches only branch names that begin with 'feature'. +- `feature$` matches only branch names that end with 'feature'. <!-- ## Troubleshooting diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index df3e24fbf30..3af7a5045c4 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' --- -# File finder +# File finder **(FREE)** > [Introduced](https://github.com/gitlabhq/gitlabhq/pull/9889) in GitLab 8.4. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 1a5e169ec6b..c8922890deb 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -31,25 +31,25 @@ Forking a project is, in most cases, a two-step process.  -The fork is created. The permissions you have in the namespace are the permissions you will have in the fork. +The fork is created. The permissions you have in the namespace are your permissions in the fork. WARNING: -When a public project with the repository feature set to "Members -only" is forked, the repository will be public in the fork. The owner -of the fork will need to manually change the visibility. This is being +When a public project with the repository feature set to **Members Only** +is forked, the repository is public in the fork. The owner +of the fork must manually change the visibility. This is being fixed in [#36662](https://gitlab.com/gitlab-org/gitlab/-/issues/36662). ## Repository mirroring You can use [repository mirroring](repository_mirroring.md) to keep your fork synced with the original repository. You can also use `git remote add upstream` to achieve the same result. -The main difference is that with repository mirroring your remote fork will be automatically kept up-to-date. +The main difference is that with repository mirroring, your remote fork is automatically kept up-to-date. -Without mirroring, to work locally you'll have to use `git pull` to update your local repository +Without mirroring, to work locally you must use `git pull` to update your local repository with the upstream project, then push the changes back to your fork to update it. WARNING: -With mirroring, before approving a merge request, you'll likely be asked to sync; hence automating it is recommended. +With mirroring, before approving a merge request, you are asked to sync. Because of this, automating it is recommended. Read more about [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). @@ -60,7 +60,7 @@ When you are ready to send your code back to the upstream project, choose your forked project's branch. For **Target branch**, choose the original project's branch. NOTE: -When creating a merge request, if the forked project's visibility is more restrictive than the parent project (for example the fork is private, the parent is public), the target branch will default to the forked project's default branch. This prevents potentially exposing the private code of the forked project. +When creating a merge request, if the forked project's visibility is more restrictive than the parent project (for example the fork is private, the parent is public), the target branch defaults to the forked project's default branch. This prevents potentially exposing the private code of the forked project.  diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 81995291911..0f49932d0c6 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -18,13 +18,12 @@ You can find the **Blame** button with each file in a project.  -When you select the **Blame** button, you'll see a screen with the -noted information: +When you select the **Blame** button, this information is shown:  -If you hover over a commit in the UI, you'll see a precise date and time -for that commit. +If you hover over a commit in the UI, the commit's precise date and time +are shown. ## Blame previous commit @@ -45,7 +44,7 @@ about a `README.md` file in the local directory, run the following command: git blame README.md ``` -You'll see output similar to the following, which includes the commit time +The output looks similar to the following, which includes the commit time in UTC format: ```shell diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 2e27cab4177..1b30a0b0f5f 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -17,13 +17,12 @@ You can find the **History** button with each file in a project.  -When you select the **History** button, you'll see a screen with the -noted information: +When you select the **History** button, this information displays:  -If you hover over a commit in the UI, you'll see a precise date and time -that commit was last modified. +If you hover over a commit in the UI, the precise date and time of the commit modification +are shown. ## Associated `git` command @@ -36,7 +35,7 @@ following command: git log README.md ``` -You'll see output similar to the following, which includes the commit +Git displays output similar to the following, which includes the commit time in UTC format: ```shell diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 1a46c140507..c41b3ed8615 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -40,7 +40,7 @@ For a commit to be verified by GitLab: ## Generating a GPG key -If you don't already have a GPG key, the following steps will help you get +If you don't already have a GPG key, the following steps can help you get started: 1. [Install GPG](https://www.gnupg.org/download/index.html) for your operating system. @@ -225,8 +225,8 @@ git config --global commit.gpgsign true ## Verifying commits 1. Within a project or [merge request](../../merge_requests/index.md), navigate to - the **Commits** tab. Signed commits will show a badge containing either - "Verified" or "Unverified", depending on the verification status of the GPG + the **Commits** tab. Signed commits show a badge containing either + **Verified** or **Unverified**, depending on the verification status of the GPG signature.  @@ -240,8 +240,8 @@ git config --global commit.gpgsign true ## Revoking a GPG key Revoking a key **unverifies** already signed commits. Commits that were -verified by using this key will change to an unverified state. Future commits -will also stay unverified once you revoke this key. This action should be used +verified by using this key changes to an unverified state. Future commits +stay unverified after you revoke this key. This action should be used in case your key has been compromised. To revoke a GPG key: @@ -282,6 +282,7 @@ For more details about GPG, see: - [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) - [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) - [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) +- [Review existing GPG keys in your instance](../../../admin_area/credentials_inventory.md#review-existing-gpg-keys) <!-- ## Troubleshooting diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 5a915ebef89..b9145364e3b 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -19,8 +19,8 @@ To create a new repository, all you need to do is Once you create a new project, you can add new files via UI (read the section below) or via command line. -To add files from the command line, follow the instructions that will -be presented on the screen when you create a new project, or read +To add files from the command line, follow the instructions +presented on the screen when you create a new project, or read through them in the [command line basics](../../../gitlab-basics/start-using-git.md) documentation. @@ -31,8 +31,7 @@ that you [connect with GitLab via SSH](../../../ssh/README.md). ## Files Use a repository to store your files in GitLab. In [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33806), -you'll see on the repository's file tree an icon next to the filename -according to its extension: +an icon identifying the extension is shown next to the filename:  @@ -76,7 +75,7 @@ markup languages](https://en.wikipedia.org/wiki/Lightweight_markup_language)) that you can use for the content of your files in a repository. They are mostly used for documentation purposes. -Just pick the right extension for your files and GitLab will render them +Just pick the right extension for your files and GitLab renders them according to the markup language. | Markup language | Extensions | @@ -93,7 +92,7 @@ according to the markup language. ### Repository README and index files -When a `README` or `index` file is present in a repository, its contents will be +When a `README` or `index` file is present in a repository, its contents are automatically pre-rendered by GitLab without opening it. They can either be plain text or have an extension of a @@ -101,12 +100,12 @@ They can either be plain text or have an extension of a Some things to note about precedence: -1. When both a `README` and an `index` file are present, the `README` will always - take precedence. +1. When both a `README` and an `index` file are present, the `README` always + takes precedence. 1. When more than one file is present with different extensions, they are - ordered alphabetically, with the exception of a file without an extension - which will always be last in precedence. For example, `README.adoc` will take - precedence over `README.md`, and `README.rst` will take precedence over + ordered alphabetically, with the exception of a file without an extension, + which is always last in precedence. For example, `README.adoc` takes + precedence over `README.md`, and `README.rst` takes precedence over `README`. ### Jupyter Notebook files @@ -159,18 +158,18 @@ Via command line, you can commit multiple times before pushing. - **Commit message:** A commit message is important to identity what is being changed and, more importantly, why. In GitLab, you can add keywords to the commit - message that will perform one of the actions below: + message that performs one of the actions below: - **Trigger a GitLab CI/CD pipeline:** If you have your project configured with [GitLab CI/CD](../../../ci/README.md), - you will trigger a pipeline per push, not per commit. + you trigger a pipeline per push, not per commit. - **Skip pipelines:** - You can add to you commit message the keyword - [`[ci skip]`](../../../ci/yaml/README.md#skip-pipeline) - and GitLab CI/CD will skip that pipeline. + You can add to your commit message the keyword + [`[ci skip]`](../../../ci/yaml/README.md#skip-pipeline), + and GitLab CI/CD skips that pipeline. - **Cross-link issues and merge requests:** [Cross-linking](../issues/crosslinking_issues.md#from-commit-messages) is great to keep track of what's is somehow related in your workflow. - If you mention an issue or a merge request in a commit message, they will be shown + If you mention an issue or a merge request in a commit message, they are shown on their respective thread. - **Cherry-pick a commit:** In GitLab, you can @@ -211,9 +210,9 @@ Find it under your project's **Repository > Graph**. ## Repository Languages -For the default branch of each repository, GitLab will determine what programming languages -were used and display this on the projects pages. If this information is missing, it will -be added after updating the default branch on the project. This process can take up to 5 +For the default branch of each repository, GitLab determines what programming languages +were used and displays this on the project's pages. If this information is missing, it's +added after updating the default branch for the project. This process can take up to five minutes.  @@ -253,8 +252,8 @@ into Xcode on macOS. To do that: 1. Click **Clone**. 1. Select **Xcode**. -The project will be cloned onto your computer in a folder of your choice and you'll -be prompted to open in XCode. +The project is cloned onto your computer in a folder of your choice and you are +prompted to open XCode. ### Clone and open in Visual Studio Code @@ -264,10 +263,10 @@ All projects can be cloned into Visual Studio Code. To do that: 1. From the GitLab UI, go to the project's overview page. 1. Click **Clone**. -1. Select **VS Code** +1. Select **VS Code**. +1. Select a folder to clone the project into. -You'll be prompted to select a folder to clone the project into. When VS Code has -successfully cloned your project, it will open the folder. +When VS Code has successfully cloned your project, it opens the folder. ## Download Source Code @@ -275,7 +274,7 @@ successfully cloned your project, it will open the folder. > - Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. The source code stored in a repository can be downloaded from the UI. -By clicking the download icon, a dropdown will open with links to download the following: +By clicking the download icon, a dropdown opens with links to download the following:  @@ -297,8 +296,8 @@ and Git push/pull redirects. Depending on the situation, different things apply. -When [renaming a user](../../profile/index.md#changing-your-username), -[changing a group path](../../group/index.md#changing-a-groups-path) or [renaming a repository](../settings/index.md#renaming-a-repository): +When [renaming a user](../../profile/index.md#change-your-username), +[changing a group path](../../group/index.md#change-a-groups-path) or [renaming a repository](../settings/index.md#renaming-a-repository): - Existing web URLs for the namespace and anything under it (such as projects) will redirect to the new URLs. diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 123df9097f9..e4a3e6d6ef1 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -12,12 +12,12 @@ type: reference interactive computing in many fields and contain a complete record of the user's sessions and include code, narrative text, equations, and rich output. -When added to a repository, Jupyter Notebooks with a `.ipynb` extension will be +When added to a repository, Jupyter Notebooks with a `.ipynb` extension are rendered to HTML when viewed.  -Interactive features, including JavaScript plots, will not work when viewed in +Interactive features, including JavaScript plots, don't work when viewed in GitLab. ## Jupyter Hub as a GitLab Managed App diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 4d5e4a5ef02..980c5417da6 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -7,19 +7,19 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.htm # Repository mirroring **(FREE)** -Repository mirroring allows for mirroring of repositories to and from external sources. It can be -used to mirror branches, tags, and commits between repositories. It is useful when you want to use +Repository mirroring allows for the mirroring of repositories to and from external sources. You +can use it to mirror branches, tags, and commits between repositories. It's useful when you want to use a repository outside of GitLab. -A repository mirror at GitLab will be updated automatically. You can also manually trigger an update -at most once every 5 minutes on GitLab.com with [the limit set by the administrator on self-managed instances](../../../administration/instance_limits.md#pull-mirroring-interval). +A repository mirror at GitLab updates automatically. You can also manually trigger an update +at most once every five minutes on GitLab.com with [the limit set by the administrator on self-managed instances](../../../administration/instance_limits.md#pull-mirroring-interval). There are two kinds of repository mirroring supported by GitLab: - [Push](#pushing-to-a-remote-repository): for mirroring a GitLab repository to another location. **(FREE)** - [Pull](#pulling-from-a-remote-repository): for mirroring a repository from another location to GitLab. **(PREMIUM)** -When the mirror repository is updated, all new branches, tags, and commits will be visible in the +When the mirror repository is updated, all new branches, tags, and commits are visible in the project's activity feed. Users with at least [Developer access](../../permissions.md) to the project can also force an @@ -37,7 +37,7 @@ The following are some possible use cases for repository mirroring: - You migrated to GitLab but still need to keep your project in another source. In that case, you can simply set it up to mirror to GitLab (pull) and all the essential history of commits, tags, - and branches will be available in your GitLab instance. **(PREMIUM)** + and branches are available in your GitLab instance. **(PREMIUM)** - 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. @@ -49,25 +49,23 @@ The following are some possible use cases for repository mirroring: ## Pushing to a remote repository **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249) in GitLab Enterprise Edition 8.7. -> - [Moved to GitLab Free](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18715) in 10.8. -> - [LFS support over HTTPS added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40137) in 13.5 +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40137) in GitLab 13.5: LFS support over HTTPS. For an existing project, you can set up push mirroring as follows: -1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section. +1. In your project, go to **Settings > Repository**, and then expand the **Mirroring repositories** section. 1. Enter a repository URL. -1. Select **Push** from the **Mirror direction** dropdown. +1. In the **Mirror direction** dropdown, select **Push**. 1. Select an authentication method from the **Authentication method** dropdown. You can authenticate with either a password or an [SSH key](#ssh-authentication). -1. Check the **Only mirror protected branches** box, if necessary. -1. Check the **Keep divergent refs** box, if desired. -1. Click the **Mirror repository** button to save the configuration. +1. Select the **Only mirror protected branches** check box, if necessary. +1. Select the **Keep divergent refs** check box, if desired. +1. Select **Mirror repository** to save the configuration.  When push mirroring is enabled, only push commits directly to the mirrored repository to prevent the -mirror diverging. All changes will end up in the mirrored repository whenever: +mirror diverging. The mirrored repository receives all changes when: - Commits are pushed to GitLab. - A [forced update](#forcing-an-update) is initiated. @@ -77,7 +75,7 @@ Changes pushed to files in the repository are automatically pushed to the remote - Within five minutes of being received. - Within one minute if **Only mirror protected branches** is enabled. -In the case of a diverged branch, you will see an error indicated at the **Mirroring repositories** +In the case of a diverged branch, an error displays in the **Mirroring repositories** section. ### Configuring push mirrors through the API @@ -87,20 +85,20 @@ You can also create and modify project push mirrors through the ### Keep divergent refs -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208828) in GitLab 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208828) in GitLab 13.0. By default, if any ref on the remote mirror has diverged from the local -repository, the *entire push* will fail, and nothing will be updated. +repository, the *entire push* fails, and no updates occur. For example, if a repository has `master`, `develop`, and `stable` branches that have been mirrored to a remote, and then a new commit is added to `develop` on -the mirror, the next push attempt will fail, leaving `master` and `stable` +the mirror, the next push attempt fails, leaving `master` and `stable` out-of-date despite not having diverged. No change on any branch can be mirrored until the divergence is resolved. With the **Keep divergent refs** option enabled, the `develop` branch is -skipped, allowing `master` and `stable` to be updated. The mirror status will -reflect that `develop` has diverged and was skipped, and be marked as a failed +skipped, allowing `master` and `stable` to be updated. The mirror status +reflects that `develop` has diverged and was skipped, and be marked as a failed update. NOTE: @@ -110,18 +108,18 @@ After the mirror is created, this option can currently only be modified via the To set up a mirror from GitLab to GitHub, you need to follow these steps: -1. Create a [GitHub personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) with the `public_repo` box checked. +1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with the `public_repo` box checked. 1. Fill in the **Git repository URL** field using this format: `https://<your_github_username>@github.com/<your_github_group>/<your_github_project>.git`. 1. Fill in **Password** field with your GitHub personal access token. -1. Click the **Mirror repository** button. +1. Select **Mirror repository**. -The mirrored repository will be listed. For example, `https://*****:*****@github.com/<your_github_group>/<your_github_project>.git`. +The mirrored repository is listed. For example, `https://*****:*****@github.com/<your_github_group>/<your_github_project>.git`. -The repository will push soon. To force a push, click the **Update now** (**{retry}**) button. +The repository pushes shortly thereafter. To force a push, select the **Update now** (**{retry}**) button. ### Setting up a push mirror from GitLab to AWS CodeCommit -AWS CodeCommit push mirroring is currently the best way to connect GitLab repositories to AWS CodePipeline, as GitLab is not yet supported as one of their Source Code Management (SCM) providers. +AWS CodeCommit push mirroring is currently the best way to connect GitLab repositories to AWS CodePipeline, as GitLab isn't yet supported as one of their Source Code Management (SCM) providers. Each new AWS CodePipeline needs significant AWS infrastructure setup. It also requires an individual pipeline per branch. @@ -159,9 +157,9 @@ To set up a mirror from GitLab to AWS CodeCommit: } ``` -1. After the user was created, click the AWS IAM user name. -1. Click the **Security credentials** tab. -1. Under **HTTPS Git credentials for AWS CodeCommit** click **Generate credentials**. +1. After the user was created, select the AWS IAM user name. +1. Select the **Security credentials** tab. +1. Under **HTTPS Git credentials for AWS CodeCommit** select **Generate credentials**. NOTE: This Git user ID and password is specific to communicating with CodeCommit. Do @@ -169,9 +167,9 @@ To set up a mirror from GitLab to AWS CodeCommit: 1. Copy or download special Git HTTPS user ID and password. 1. In the AWS CodeCommit console, create a new repository to mirror from your GitLab repository. -1. Open your new repository and click **Clone URL > Clone HTTPS** (not **Clone HTTPS (GRC)**). +1. Open your new repository, and then select **Clone URL > Clone HTTPS** (not **Clone HTTPS (GRC)**). 1. In GitLab, open the repository to be push-mirrored. -1. Click **Settings > Repository** and expand **Mirroring repositories**. +1. Go to **Settings > Repository**, and then expand **Mirroring repositories**. 1. Fill in the **Git repository URL** field using this format: ```plaintext @@ -185,17 +183,17 @@ To set up a mirror from GitLab to AWS CodeCommit: 1. For **Authentication method**, select **Password** and fill in the **Password** field with the special IAM Git clone user ID **password** created earlier in AWS. 1. The option **Only mirror protected branches** should be good for CodeCommit as it pushes more frequently (from every five minutes to every minute). - CodePipeline requires individual pipeline setups for named branches you wish to have a AWS CI setup for. Since feature branches that have dynamic names will not be supported anyway, configuring **Only mirror protected branches** does not cause flexibility problems with CodePipeline integration as long as you are also willing to protect all the named branches you want to build CodePipelines for. + CodePipeline requires individual pipeline setups for named branches you wish to have a AWS CI setup for. Because feature branches that have dynamic names are unsupported, configuring **Only mirror protected branches** doesn't cause flexibility problems with CodePipeline integration as long as you are also willing to protect all the named branches you want to build CodePipelines for. -1. Click **Mirror repository**. You should see the mirrored repository appear: +1. Select **Mirror repository**. You should see the mirrored repository appear: ```plaintext https://*****:*****@git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo> ``` -To test mirroring by forcing a push, click the half-circle arrows button (hover text is **Update now**). +To test mirroring by forcing a push, select the half-circle arrows button (hover text is **Update now**). If **Last successful update** shows a date, you have configured mirroring correctly. -If it is not working correctly a red `error` tag appears and shows the error message as hover text. +If it isn't working correctly, a red `error` tag appears and shows the error message as hover text. ### Setting up a push mirror to another GitLab instance with 2FA activated @@ -203,11 +201,10 @@ If it is not working correctly a red `error` tag appears and shows the error mes 1. On the source GitLab instance: 1. Fill in the **Git repository URL** field using this format: `https://oauth2@<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`. 1. Fill in the **Password** field with the GitLab personal access token created on the destination GitLab instance. - 1. Click the **Mirror repository** button. + 1. Select **Mirror repository**. ## Pulling from a remote repository **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51) in GitLab Enterprise Edition 8.2. > - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/-/issues/10871) in GitLab 11.11. > - Moved to GitLab Premium in 13.9. @@ -219,16 +216,20 @@ to be able to browse its content and its activity using the familiar GitLab inte To configure mirror pulling for an existing project: -1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** - section. -1. Enter a repository URL. -1. Select **Pull** from the **Mirror direction** dropdown. -1. Select an authentication method from the **Authentication method** dropdown, if necessary. -1. If necessary, check the following boxes: - - **Overwrite diverged branches**. - - **Trigger pipelines for mirror updates**. - - **Only mirror protected branches**. -1. Click the **Mirror repository** button to save the configuration. +1. If you [configured two-factor authentication (2FA)](https://docs.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa) + for GitHub, create a [personal access token for GitHub](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) + with the `read_repository` scope. If 2FA is enabled, this personal access + token serves as your GitHub password. +1. In your project, go to **Settings > Repository**, and then expand the + **Mirroring repositories** section. +1. In the **Git repository URL** field, enter a repository URL. +1. In the **Mirror direction** dropdown, select **Pull**. +1. In the **Authentication method** dropdown, select your authentication method. +1. Select from the following checkboxes, if needed: + - **Overwrite diverged branches** + - **Trigger pipelines for mirror updates** + - **Only mirror protected branches** +1. Select **Mirror repository** to save the configuration.  @@ -238,15 +239,15 @@ To configure mirror pulling for an existing project: Because GitLab is now set to pull changes from the upstream repository, you should not push commits directly to the repository on GitLab. Instead, any commits should be pushed to the remote repository. -Changes pushed to the remote repository will be pulled into the GitLab repository, either: +Changes pushed to the remote repository are pulled into the GitLab repository, either: - Automatically within a certain period of time. - When a [forced update](#forcing-an-update) is initiated. WARNING: -If you do manually update a branch in the GitLab repository, the branch will become diverged from -upstream and GitLab will no longer automatically update this branch to prevent any changes from being lost. -Also note that deleted branches and tags in the upstream repository will not be reflected in the GitLab repository. +If you do manually update a branch in the GitLab repository, the branch becomes diverged from +upstream, and GitLab no longer automatically updates this branch to prevent any changes from being lost. +Deleted branches and tags in the upstream repository are not reflected in the GitLab repository. ### How it works @@ -259,13 +260,12 @@ Once per minute, a Sidekiq cron job schedules repository mirrors to update, base Repository mirrors are updated as Sidekiq becomes available to process them. If the process of updating the repository mirror: -- Succeeds, an update will be enqueued again with at least a 30 minute wait. -- Fails (for example, a branch diverged from upstream), it will be attempted again later. Mirrors can fail - up to 14 times before they will not be enqueued for update again. +- **Succeeds**: An update is enqueued again with at least a 30 minute wait. +- **Fails**: (For example, a branch diverged from upstream.), The update attempted again later. Mirrors can fail + up to 14 times before they are no longer enqueued for updates. ### Overwrite diverged branches **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4559) in GitLab 10.6. > - Moved to GitLab Premium in 13.9. You can choose to always update your local branches with remote versions, even if they have @@ -278,42 +278,39 @@ To use this option, check the **Overwrite diverged branches** box when creating ### Trigger pipelines for mirror updates **(PREMIUM)** -> Moved to GitLab Premium in 13.9. +> - Moved to GitLab Premium in 13.9. -If this option is enabled, pipelines will be triggered when branches or tags are +If this option is enabled, pipelines trigger when branches or tags are updated from the remote repository. Depending on the activity of the remote repository, this may greatly increase the load on your CI runners. Only enable -this if you know they can handle the load. CI will run using the credentials +this if you know they can handle the load. CI uses the credentials assigned when you set up pull mirroring. ### Hard failure **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3117) in GitLab 10.2. > - Moved to GitLab Premium in 13.9. -Once the mirroring process is unsuccessfully retried 14 times in a row, it will get marked as hard -failed. This will become visible in either the: +After 14 consecutive unsuccessful retries, the mirroring process is marked as a hard failure +and mirroring attempts stop. This failure is visible in either the: - Project's main dashboard. - Pull mirror settings page. -When a project is hard failed, it will no longer get picked up for mirroring. You can resume the project mirroring again by [forcing an update](#forcing-an-update). ### Trigger an update using the API **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3453) in GitLab 10.3. > - Moved to GitLab Premium in 13.9. Pull mirroring uses polling to detect new branches and commits added upstream, often minutes afterwards. If you notify GitLab by [API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project), -updates will be pulled immediately. +updates are 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). ## Mirror only protected branches **(PREMIUM)** -> Moved to GitLab Premium in 13.9. +> - Moved to GitLab Premium in 13.9. Based on the mirror direction that you choose, you can opt to mirror only the [protected branches](../protected_branches.md) from/to your remote repository. @@ -324,7 +321,6 @@ creating a repository mirror. **(PREMIUM)** ## SSH authentication -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2551) in GitLab 9.5 for Pull mirroring. > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) in GitLab 11.6 for Push mirroring. SSH authentication is mutual: @@ -336,15 +332,15 @@ You provide your credentials as a password or public key. The server that the other repository resides on provides its credentials as a "host key", the fingerprint of which needs to be verified manually. -If you're mirroring over SSH (that is, using an `ssh://` URL), you can authenticate using: +If you're mirroring over SSH (using an `ssh://` URL), you can authenticate using: - Password-based authentication, just as over HTTPS. - Public key authentication. This is often more secure than password authentication, - especially when the other repository supports [deploy keys](../../../ssh/README.md#deploy-keys). + especially when the other repository supports [deploy keys](../deploy_keys/index.md). To get started: -1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section. +1. In your project, go to **Settings > Repository**, and then expand the **Mirroring repositories** section. 1. Enter an `ssh://` URL for mirroring. NOTE: @@ -355,9 +351,9 @@ Entering the URL adds two buttons to the page: - **Detect host keys**. - **Input host keys manually**. -If you click the: +If you select the: -- **Detect host keys** button, GitLab will fetch the host keys from the server and display the fingerprints. +- **Detect host keys** button, GitLab fetches the host keys from the server and display the fingerprints. - **Input host keys manually** button, a field is displayed where you can paste in host keys. Assuming you used the former, you now need to verify that the fingerprints are @@ -366,13 +362,13 @@ fingerprints in the open for you to check: - [AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints) - [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/) -- [GitHub](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/githubs-ssh-key-fingerprints) +- [GitHub](https://docs.github.com/en/github/authenticating-to-github/githubs-ssh-key-fingerprints) - [GitLab.com](../../gitlab_com/index.md#ssh-host-keys-fingerprints) - [Launchpad](https://help.launchpad.net/SSHFingerprints) - [Savannah](http://savannah.gnu.org/maintenance/SshAccess/) - [SourceForge](https://sourceforge.net/p/forge/documentation/SSH%20Key%20Fingerprints/) -Other providers will vary. If you're running self-managed GitLab, or otherwise +Other providers vary. If you're running self-managed GitLab, or otherwise have access to the server for the other repository, you can securely gather the key fingerprints: @@ -386,28 +382,28 @@ $ cat /etc/ssh/ssh_host*pub | ssh-keygen -E md5 -l -f - NOTE: You may need to exclude `-E md5` for some older versions of SSH. -When mirroring the repository, GitLab will now check that at least one of the +When mirroring the repository, GitLab checks that at least one of the stored host keys matches before connecting. This can prevent malicious code from being injected into your mirror, or your password being stolen. ### SSH public key authentication -To use SSH public key authentication, you'll also need to choose that option +To use SSH public key authentication, you must also choose that option from the **Authentication method** dropdown. When the mirror is created, -GitLab generates a 4096-bit RSA key that can be copied by clicking the **Copy SSH public key** button. +GitLab generates a 4096-bit RSA key that can be copied by selecting the **Copy SSH public key** button.  You then need to add the public SSH key to the other repository's configuration: - If the other repository is hosted on GitLab, you should add the public SSH key - as a [deploy key](../../../ssh/README.md#deploy-keys). + as a [deploy key](../../project/deploy_keys/index.md). - If the other repository is hosted elsewhere, you may need to add the key to your user's `authorized_keys` file. Paste the entire public SSH key into the file on its own line and save it. If you need to change the key at any time, you can remove and re-add the mirror -to generate a new key. You'll have to update the other repository with the new +to generate a new key. Update the other repository with the new key to keep the mirror running. NOTE: @@ -423,17 +419,17 @@ update button which is available on the **Mirroring repositories** section of th ## Bidirectional mirroring **(PREMIUM)** -> Moved to GitLab Premium in 13.9. +> - Moved to GitLab Premium in 13.9. WARNING: Bidirectional mirroring may cause conflicts. If you configure a GitLab repository to both pull from, and push to, the same remote source, there -is no guarantee that either repository will update correctly. If you set up a repository for -bidirectional mirroring, you should prepare for the likely conflicts by deciding who will resolve -them and how they will be resolved. +is no guarantee that either repository updates correctly. If you set up a repository for +bidirectional mirroring, you should prepare for the likely conflicts by deciding who resolves +them and how. -Rewriting any mirrored commit on either remote will cause conflicts and mirroring to fail. This can +Rewriting any mirrored commit on either remote causes conflicts and mirroring to fail. This can be prevented by [mirroring only protected branches](#mirror-only-protected-branches). You should [protect the branches](../protected_branches.md) you wish to mirror on both @@ -447,34 +443,35 @@ protected branches. ### Configure a webhook to trigger an immediate pull to GitLab -Assuming you have already configured the [push](#setting-up-a-push-mirror-to-another-gitlab-instance-with-2fa-activated) and [pull](#pulling-from-a-remote-repository) mirrors in the upstream GitLab instance, to trigger an immediate pull as suggested above, you 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 must 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) request to trigger an immediate pull after updates to the repository. +1. Create a [personal access token](../../profile/personal_access_tokens.md) with `API` scope. +1. In your project, go to **Settings > Webhooks**. +1. Add the webhook URL which (in this case) uses the [Pull Mirror API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) request to trigger an immediate pull after updates to the repository. - ```plaintext - https://gitlab.example.com/api/v4/projects/:id/mirror/pull?private_token=<your_access_token> - ``` + ```plaintext + https://gitlab.example.com/api/v4/projects/:id/mirror/pull?private_token=<your_access_token> + ``` + +1. Ensure the **Push Events** checkbox is selected. +1. Select **Add Webhook** to save the webhook. -- Ensure that the **Push Events** checkbox is selected. -- Click on **Add Webhook** button to save the webhook. -- To test the integration click on the **Test** button and confirm GitLab does not return any error. +To test the integration, select the **Test** button and confirm GitLab doesn't return an error message. ### Preventing conflicts using a `pre-receive` hook WARNING: -The solution proposed will negatively impact the performance of -Git push operations because they will be proxied to the upstream Git +The solution proposed negatively affects the performance of +Git push operations because they are proxied to the upstream Git repository. A server-side `pre-receive` hook can be used to prevent the race condition described above by only accepting the push after first pushing the commit to the upstream Git repository. In this configuration one Git repository acts as the authoritative upstream, and the other as downstream. The `pre-receive` hook -will be installed on the downstream repository. +is installed on the downstream repository. Read about [configuring Server hooks](../../../administration/server_hooks.md) on the GitLab server. @@ -540,11 +537,11 @@ fi Note that this sample has a few limitations: - This example may not work verbatim for your use case and might need modification. - - It does not regard different types of authentication mechanisms for the mirror. - - It does not work with forced updates (rewriting history). - - Only branches that match the `allowlist` patterns will be proxy pushed. + - It doesn't regard different types of authentication mechanisms for the mirror. + - It doesn't work with forced updates (rewriting history). + - Only branches that match the `allowlist` patterns are proxy pushed. - The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO` - is seen as a ref update and Git will complain about it. + is seen as a ref update, and Git displays warnings about it. ### Mirroring with Perforce Helix via Git Fusion **(PREMIUM)** @@ -560,22 +557,22 @@ mirror projects with GitLab. This may be useful in some situations when migratin to GitLab where overlapping Perforce Helix workspaces cannot be migrated simultaneously to GitLab. If using mirroring with Perforce Helix, you should only mirror protected branches. Perforce Helix -will reject any pushes that rewrite history. Only the fewest number of branches should be mirrored +rejects any pushes that rewrite history. Only the fewest number of branches should be mirrored due to the performance limitations of Git Fusion. When configuring mirroring with Perforce Helix via Git Fusion, the following Git Fusion settings are recommended: -- `change-pusher` should be disabled. Otherwise, every commit will be rewritten as being committed +- `change-pusher` should be disabled. Otherwise, every commit is rewritten as being committed by the mirroring account, rather than being mapped to existing Perforce Helix users or the `unknown_git` user. -- `unknown_git` user will be used as the commit author if the GitLab user does not exist in +- `unknown_git` user is used as the commit author if the GitLab user doesn't exist in Perforce Helix. Read about [Git Fusion settings on Perforce.com](https://www.perforce.com/manuals/git-fusion/Content/Git-Fusion/section_vss_bdw_w3.html#section_zdp_zz1_3l). ## Troubleshooting -Should an error occur during a push, GitLab will display an "Error" highlight for that repository. Details on the error can then be seen by hovering over the highlight text. +Should an error occur during a push, GitLab displays an **Error** highlight for that repository. Details on the error can then be seen by hovering over the highlight text. ### 13:Received RST_STREAM with error code 2 with GitHub @@ -584,3 +581,9 @@ If you receive an "13:Received RST_STREAM with error code 2" while mirroring to ### 4:Deadline Exceeded When upgrading to GitLab 11.11.8 or newer, a change in how usernames are represented means that you may need to update your mirroring username and password to ensure that `%40` characters are replaced with `@`. + +### Connection blocked because server only allows public key authentication + +As the error indicates, the connection is getting blocked between GitLab and the remote repository. Even if a [TCP Check](../../../administration/raketasks/maintenance.md#check-tcp-connectivity-to-a-remote-site) is successful, you must check any networking components in the route from GitLab to the remote Server to ensure there's no blockage. + +For example, we've seen this error when a Firewall was performing a `Deep SSH Inspection` on outgoing packets. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index a9e249bb8c3..efa35c1ceac 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# GitLab Web Editor +# GitLab Web Editor **(FREE)** 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 @@ -108,7 +108,7 @@ You can see a **Create merge request** dropdown below the issue description. The **Create merge request** button doesn't display if: - A branch with the same name already exists. -- The branch already has a referenced merge request. +- A merge request already exists for this branch. - Your project has an active fork relationship. To make this button appear, one possible workaround is to diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 29c1c32145d..c89f3a267ba 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -39,7 +39,7 @@ recommend using certificates from a PKI that are in line with ## Obtaining an X.509 key pair -If your organization has Public Key Infrastructure (PKI), that PKI will provide +If your organization has Public Key Infrastructure (PKI), that PKI provides an S/MIME key. If you do not have an S/MIME key pair from a PKI, you can either create your @@ -49,7 +49,7 @@ and some of them generate keys for free. ## Associating your X.509 certificate with Git -To take advantage of X.509 signing, you will need Git 2.19.0 or later. You can +To take advantage of X.509 signing, you need Git 2.19.0 or later. You can check your Git version with: ```shell diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index c7dda81685c..bd37acafd22 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -96,18 +96,20 @@ As soon as a requirement is reopened, it no longer appears in the **Archived** t ## Search for a requirement -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212543) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212543) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. +> - Searching by status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/224614) in GitLab 13.10. You can search for a requirement from the requirements list page based on the following criteria: -- Requirement title +- Title - Author's username +- Status (satisfied, failed, or missing) To search for a requirement: 1. In a project, go to **Requirements > List**. 1. Select the **Search or filter results** field. A dropdown menu appears. -1. Select the requirement author from the dropdown or enter plain text to search by requirement title. +1. Select the requirement author or status from the dropdown or enter plain text to search by requirement title. 1. Press <kbd>Enter</kbd> on your keyboard to filter the list. You can also sort the requirements list by: @@ -183,7 +185,7 @@ requirements_confirmation: ### Add the manual job to CI conditionally To configure your CI to include the manual job only when there are some open -requirements, add a rule which checks `CI_HAS_OPEN_REQUIREMENTS` CI variable. +requirements, add a rule which checks `CI_HAS_OPEN_REQUIREMENTS` CI/CD variable. ```yaml requirements_confirmation: diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index debe5c51d51..383b4df9612 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -73,7 +73,7 @@ To enable Service Desk in your project: 1. Enable the **Activate Service Desk** toggle. This reveals a unique email address to email issues to the project. -Service Desk is now enabled for this project! To access it in a project, in the left sidebar, select +Service Desk is now enabled for this project! To access it in a project, in the left sidebar, select **Issues > Service Desk**. WARNING: @@ -137,13 +137,13 @@ You can use these placeholders to be automatically replaced in each email: #### New Service Desk issues -You can select one [issue description template](description_templates.md#creating-issue-templates) +You can select one [issue description template](description_templates.md#create-an-issue-template) **per project** to be appended to every new Service Desk issue's description. Issue description templates should reside in your repository's `.gitlab/issue_templates/` directory. To use a custom issue template with Service Desk, in your project: -1. [Create a description template](description_templates.md#creating-issue-templates) +1. [Create a description template](description_templates.md#create-an-issue-template) 1. Go to **Settings > General > Service Desk**. 1. From the dropdown **Template to append to all Service Desk issues**, select your template. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 6f230f1798a..7b5a0cbb377 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -118,16 +118,16 @@ The following items will be exported: - Issue boards - Pipelines history - Push Rules +- Awards The following items will **not** be exported: - Build traces and artifacts - Container registry images -- CI variables +- CI/CD variables - Webhooks - Any encrypted tokens - Merge Request Approvers -- Awards NOTE: For more details on the specific data persisted in a project export, see the diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 8ab82fe7296..785618a862a 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -44,6 +44,7 @@ Compliance framework labels do not affect your project settings. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. > - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It can be enabled or disabled for a single group > - It's disabled on GitLab.com. > - It's not recommended for production use. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-custom-compliance-frameworks). **(PREMIUM)** @@ -103,8 +104,7 @@ Some features depend on others: When the **Issues** option is disabled, you can still access **Milestones** from merge requests. -- Additionally, if you disable both **Issues** and **Merge Requests**, you will no - longer have access to: +- Additionally, if you disable both **Issues** and **Merge Requests**, you cannot access: - **Labels** - **Milestones** @@ -220,7 +220,7 @@ To rename a repository: 1. Click **Change path**. Remember that this can have unintended side effects since everyone with the -old URL won't be able to push or pull. Read more about what happens with the +old URL can't push or pull. Read more about what happens with the [redirects when renaming repositories](../repository/index.md#redirects-when-changing-repository-paths). #### Transferring an existing project into another namespace @@ -243,7 +243,7 @@ To transfer a project: project to. 1. Confirm the transfer by typing the project's path as instructed. -Once done, you will be taken to the new project's namespace. At this point, +Once done, you are redirected to the new project's namespace. At this point, read what happens with the [redirects from the old project to the new one](../repository/index.md#redirects-when-changing-repository-paths). @@ -266,7 +266,7 @@ This action: - Deletes a project including all associated resources (issues, merge requests etc). - From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium](https://about.gitlab.com/pricing/) or higher tiers, -group owners can [configure](../../group/index.md#enabling-delayed-project-removal) projects within a group +group owners can [configure](../../group/index.md#enable-delayed-project-removal) projects within a group to be deleted after a delayed period. When enabled, actual deletion happens after number of days specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). @@ -293,7 +293,7 @@ If you want to use the fork for yourself and don't need to send you can safely remove the fork relationship. WARNING: -Once removed, the fork relationship cannot be restored. You will no longer be able to send merge requests to the source, and if anyone has forked your project, their fork will also lose the relationship. +Once removed, the fork relationship cannot be restored. You can't send merge requests to the source, and if anyone has forked your project, their fork also loses the relationship. To do so: @@ -330,11 +330,11 @@ can enable it. To enable it: ```ruby -Feature.enable(:ff_custom_compliance_frameworks) +Feature.enable(:ff_custom_compliance_frameworks, Group.find(<group id>)) ``` To disable it: ```ruby -Feature.disable(:ff_custom_compliance_frameworks) +Feature.disable(:ff_custom_compliance_frameworks, Group.find(<group id>)) ``` diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 590f549577e..cda39508835 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -78,33 +78,3 @@ the following table. | `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | | `read_repository` | Allows read-only access (pull) to the repository. | | `write_repository` | Allows read-write access (pull, push) to the repository. | - -### Enable or disable project access tokens - -Project access tokens are deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable it for your instance, globally or by project. - -To disable it globally: - -```ruby -Feature.disable(:resource_access_token) -``` - -To disable it for a specific project: - -```ruby -Feature.disable(:resource_access_token, project) -``` - -To enable it globally: - -```ruby -Feature.enable(:resource_access_token) -``` - -To enable it for a specific project: - -```ruby -Feature.enable(:resource_access_token, project) -``` diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 002eb398406..431250a817d 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -102,7 +102,7 @@ To edit a file: in the bottom-right corner. 1. When you're done, click **Submit changes...**. 1. (Optional) Adjust the default title and description of the merge request, to submit - with your changes. Alternatively, select a [merge request template](../../../user/project/description_templates.md#creating-merge-request-templates) + with your changes. Alternatively, select a [merge request template](../../../user/project/description_templates.md#create-a-merge-request-template) from the dropdown menu and edit it accordingly. 1. Click **Submit changes**. 1. A new merge request is automatically created and you can assign a colleague for review. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 2b0ca38c57c..d1e9fe155b4 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -40,7 +40,8 @@ Below is an example of how you can use those new quick actions inside a comment.  -Adding time entries (time spent or estimates) is limited to project members. +Adding time entries (time spent or estimates) is limited to project members +with [Reporter and higher permission levels](../permissions.md). ### Estimates diff --git a/doc/user/project/web_ide/img/solarized_dark_theme_v13_1.png b/doc/user/project/web_ide/img/solarized_dark_theme_v13_1.png Binary files differindex ccb9cf6f126..8eca352a4d0 100644 --- a/doc/user/project/web_ide/img/solarized_dark_theme_v13_1.png +++ b/doc/user/project/web_ide/img/solarized_dark_theme_v13_1.png diff --git a/doc/user/project/web_ide/img/solarized_light_theme_v13_0.png b/doc/user/project/web_ide/img/solarized_light_theme_v13_0.png Binary files differdeleted file mode 100644 index 6257d78d29e..00000000000 --- a/doc/user/project/web_ide/img/solarized_light_theme_v13_0.png +++ /dev/null diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 07f46cb94f7..57b79875909 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -71,19 +71,16 @@ Single file editing is based on the [Ace Editor](https://ace.c9.io). ### Themes -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in GitLab in 13.0. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in GitLab 13.0. > - Full Solarized Dark Theme [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219228) in GitLab 13.1. +> - Full [Solarized Light](https://gitlab.com/gitlab-org/gitlab/-/issues/221035) and [Monokai](https://gitlab.com/gitlab-org/gitlab/-/issues/221034) Themes introduced in GitLab 13.6. -All the themes GitLab supports for syntax highlighting are added to the Web IDE's code editor. +All the themes GitLab supports for syntax highlighting are applied to the Web IDE's entire screen. 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 | -|---------------------------------------------------------------|-------------------------------------------------------------|-----------------------------------------| -|  |  |  | +| Solarized Dark Theme | Dark Theme | +|-------------------------------------------------------------|-----------------------------------------| +|  |  | ## Schema based validation @@ -237,7 +234,7 @@ different branch. When you edit Markdown files in the Web IDE, you can preview your changes by clicking the **Preview Markdown** tab above the file editor. The Markdown preview -supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). +supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). You can also upload any local images by pasting them directly in the Markdown file. The image is uploaded to the same directory and is named `image.png` by default. @@ -424,7 +421,7 @@ terminal: See [this issue](https://gitlab.com/gitlab-org/webide-file-sync/-/issues/7) for more information. - `$CI_PROJECT_DIR` is a - [predefined environment variable](../../../ci/variables/predefined_variables.md) + [predefined CI/CD variable](../../../ci/variables/predefined_variables.md) for GitLab Runners. This is where your project's repository resides. After you have configured the web terminal for file syncing, then when the web diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 187fcb5b3f9..eb8270b8740 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -24,9 +24,9 @@ a separate Git repository. ## First time creating the Home page -The first time you visit a Wiki, you will be directed to create the Home page. -The Home page is necessary to be created since it serves as the landing page -when viewing a Wiki. You only have to fill in the **Content** section and click +The first time you visit a Wiki, you are directed to create the Home page. +The Home page is necessary to be created because it serves as the landing page +when viewing a Wiki. Complete the **Content** section, and then select **Create page**. You can always edit it later, so go ahead and write a welcome message. @@ -37,38 +37,38 @@ message. NOTE: Requires Developer [permissions](../../permissions.md). -Create a new page by clicking the **New page** button that can be found +Create a new page by selecting the **New page** button that can be found in all wiki pages. -You will be asked to fill in a title for your new wiki page. +Enter a title for your new wiki page. You can specify a full path for the wiki page by using '/' in the -title to indicate subdirectories. Any missing directories will be created -automatically. For example, a title of `docs/my-page` will create a wiki +title to indicate subdirectories. Any missing directories are created +automatically. For example, a title of `docs/my-page` creates a wiki page with a path `/wikis/docs/my-page`. -Once you enter the page name, it's time to fill in its content. GitLab wikis +After you enter the page name, it's time to fill in its content. GitLab wikis support Markdown, RDoc, AsciiDoc, and Org. For Markdown based pages, all the [Markdown features](../../markdown.md) are supported and for links there is some [wiki specific](../../markdown.md#wiki-specific-markdown) behavior. In the web interface the commit message is optional, but the GitLab Wiki is -based on Git and needs a commit message, so one will be created for you if you -do not enter one. +based on Git and needs a commit message, so one is created for you if you +don't enter one. -When you're ready, click the **Create page** and the new page will be created. +When you're ready, select **Create page** and the new page is created.  ### Attachment storage -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475) in GitLab 11.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475) in GitLab 11.3. -Starting with GitLab 11.3, any file that is uploaded to the wiki via the GitLab -interface will be stored in the wiki Git repository, and it will be available +Any file uploaded to the wiki with the GitLab +interface is stored in the wiki Git repository, and is available if you clone the wiki repository locally. All uploaded files prior to GitLab 11.3 are stored in GitLab itself. If you want them to be part of the wiki's Git -repository, you will have to upload them again. +repository, you must upload them again. ### Special characters in page titles @@ -80,7 +80,7 @@ Wiki pages are stored as files in a Git repository, so certain characters have a ### Length restrictions for file and directory names -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24364) in GitLab 12.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24364) in GitLab 12.8. Many common file systems have a [limit of 255 bytes for file and directory names](https://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits), and while Git and GitLab both support paths exceeding those limits, the presence of them makes it impossible for users on those file systems to checkout a wiki repository locally. @@ -99,9 +99,9 @@ Please note that: You need Developer [permissions](../../permissions.md) or higher to edit a wiki page. To do so: -1. Click the edit icon (**{pencil}**). +1. Select the edit icon (**{pencil}**). 1. Edit the content. -1. Click **Save changes**. +1. Select **Save changes**. ### Adding a table of contents @@ -114,7 +114,7 @@ You need Maintainer [permissions](../../permissions.md) or higher to delete a wi To do so: 1. Open the page you want to delete. -1. Click the **Delete page** button. +1. Select **Delete page**. 1. Confirm the deletion. ## Moving a wiki page @@ -122,22 +122,22 @@ To do so: You need Developer [permissions](../../permissions.md) or higher to move a wiki page. To do so: -1. Click the edit icon (**{pencil}**). +1. Select the edit icon (**{pencil}**). 1. Add the new path to the **Title** field. -1. Click **Save changes**. +1. Select **Save changes**. For example, if you have a wiki page called `about` under `company` and you want to move it to the wiki's root: -1. Click the edit icon (**{pencil}**). +1. Select the edit icon (**{pencil}**). 1. Change the **Title** from `about` to `/about`. -1. Click **Save changes**. +1. Select **Save changes**. If you want to do the opposite: -1. Click the edit icon (**{pencil}**). +1. Select the edit icon (**{pencil}**). 1. Change the **Title** from `about` to `company/about`. -1. Click **Save changes**. +1. Select **Save changes**. ## Viewing a list of all created wiki pages @@ -148,41 +148,41 @@ found. The list is ordered alphabetically.  -If you have many pages, not all will be listed in the sidebar. Click on +If you have many pages, not all are listed in the sidebar. Select **View All Pages** to see all of them. ## Viewing the history of a wiki page The changes of a wiki page over time are recorded in the wiki's Git repository, -and you can view them by clicking the **Page history** button. +and you can view them by selecting **Page history**. From the history page you can see the revision of the page (Git commit SHA), its author, the commit message, and when it was last updated. -To see how a previous version of the page looked like, click on a revision +To see how a previous version of the page looked like, select a revision number in the **Page version** column.  ### Viewing the changes between page versions -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15242) in GitLab 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15242) in GitLab 13.2. Similar to versioned diff file views, you can see the changes made in a given Wiki page version: 1. Navigate to the Wiki page you're interested in. -1. Click on **Page history** to see all page versions. -1. Click on the commit message in the **Changes** column for the version you're interested in: +1. Select **Page history** to see all page versions. +1. Select the commit message in the **Changes** column for the version you're interested in.  ## Wiki activity records > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14902) in **GitLab 12.10.** -> - Git events were [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in **GitLab 13.0.** +> - Git events were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in **GitLab 13.0.** > - [Feature flag for Git events was removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258665) in **GitLab 13.5** Wiki events (creation, deletion, and updates) are tracked by GitLab and -displayed on the [user profile](../../profile/index.md#user-profile), +displayed on the [user profile](../../profile/index.md#access-your-user-profile), [group](../../group/index.md#view-group-activity), and [project](../working_with_projects.md#project-activity) activity pages. @@ -191,12 +191,12 @@ and [project](../working_with_projects.md#project-activity) activity pages. Since wikis are based on Git repositories, you can clone them locally and edit them like you would do with every other Git repository. -On the right sidebar, click on **Clone repository** and follow the on-screen +In the right sidebar, select **Clone repository** and follow the on-screen instructions. Files that you add to your wiki locally must have one of the following supported extensions, depending on the markup language you wish to use, -otherwise they will not display when pushed to GitLab: +otherwise they don't display when pushed to GitLab: - Markdown extensions: `.mdown`, `.mkd`, `.mkdn`, `.md`, `.markdown`. - AsciiDoc extensions: `.adoc`, `.ad`, `.asciidoc`. @@ -204,11 +204,11 @@ otherwise they will not display when pushed to GitLab: ## Customizing sidebar -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by clicking the **Edit sidebar** button. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. To customize the Wiki's navigation sidebar, you need Developer permissions to the project. -On the top-right, click **Edit sidebar** and make your changes. This creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation. +In the top-right, select **Edit sidebar** and make your changes. This creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation. Example for `_sidebar` (using Markdown format): diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 3fe6193c414..43df1cce70f 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -212,7 +212,7 @@ To delete a project, first navigate to the home page for that project. 1. Click **Delete project** 1. Confirm this action by typing in the expected text. -Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects in a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal). +Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects in a group, please see [Enable delayed project removal](../group/index.md#enable-delayed-project-removal). ## Project settings @@ -278,7 +278,7 @@ databases if the module name or a prefix of it appears in `GONOPRIVATE` or ### Authenticate Go requests To authenticate requests to private projects made by Go, use a [`.netrc` -file](https://ec.haxx.se/usingcurl-netrc.html) and a [personal access +file](https://everything.curl.dev/usingcurl/netrc) and a [personal access token](../profile/personal_access_tokens.md) in the password field. **This only works if your GitLab instance can be accessed with HTTPS.** The `go` command does not transmit credentials over insecure connections. This authenticates |
