diff options
Diffstat (limited to 'doc/user/project')
246 files changed, 1662 insertions, 1162 deletions
diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index ff9cb1c712e..1aa040c9cb8 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference description: "Autocomplete chars in Markdown fields." --- diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index fd0287fb5fb..f7bb88c33aa 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -84,7 +84,7 @@ are available: - `%{commit_sha}`: ID of the most recent commit to the default branch of a project's repository -NOTE: **Note:** +NOTE: Placeholders allow badges to expose otherwise-private information, such as the default branch or commit SHA when the project is configured to have a private repository. This is by design, as badges are intended to be used publicly. Avoid diff --git a/doc/user/project/builds/artifacts.md b/doc/user/project/builds/artifacts.md index 1b0f3f61394..e7572b4ff1f 100644 --- a/doc/user/project/builds/artifacts.md +++ b/doc/user/project/builds/artifacts.md @@ -3,3 +3,6 @@ redirect_to: '../pipelines/job_artifacts.md' --- This document was moved to [pipelines/job_artifacts](../pipelines/job_artifacts.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/bulk_editing.md b/doc/user/project/bulk_editing.md index 98584a939ea..a29c0754d31 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -1,12 +1,12 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Bulk editing issues and merge requests at the project level -NOTE: **Note:** +NOTE: Bulk editing issues, epics, and merge requests is also available at the **group level**. For more details, see [Bulk editing issues, epics, and merge requests at the group level](../group/bulk_editing/index.md). @@ -14,14 +14,14 @@ For more details, see If you want to update attributes across multiple issues or merge requests, you can do it by bulk editing them, that is, editing them together. -NOTE: **Note:** +NOTE: Only the items visible on the current page are selected for bulk editing (up to 20).  ## Bulk edit issues at the project level -NOTE: **Note:** +NOTE: You need a permission level of [Reporter or higher](../permissions.md) to manage issues. When bulk editing issues in a project, you can edit the following attributes: @@ -46,7 +46,7 @@ To update multiple project issues at the same time: ## Bulk edit merge requests at the project level -NOTE: **Note:** +NOTE: You need a permission level of [Developer or higher](../permissions.md) to manage merge requests. When bulk editing merge requests in a project, you can edit the following attributes: diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index e9bb6d0e3ff..52c825932fa 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Canary Deployments **(PREMIUM)** @@ -32,13 +32,13 @@ deployments right inside the [Deploy Board](deploy_boards.md), without the need Canary deployments can be used when you want to ship features to only a portion of your pods fleet and watch their behavior as a percentage of your user base visits the temporarily deployed feature. If all works well, you can deploy the -feature to production knowing that it won't cause any problems. +feature to production knowing that it shouldn't cause any problems. Canary deployments are also especially useful for backend refactors, performance improvements, or other changes where the user interface doesn't change, but you want to make sure the performance stays the same, or improves. Developers need to be careful when using canaries with user-facing changes, because by default, -requests from the same user will be randomly distributed between canary and +requests from the same user are randomly distributed between canary and non-canary pods, which could result in confusion or even errors. If needed, you may want to consider [setting `service.spec.sessionAffinity` to `ClientIP` in your Kubernetes service definitions](https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies), but that is beyond the scope of @@ -60,7 +60,7 @@ This allows GitLab to discover whether a deployment is stable or canary (tempora Once all of the above are set up and the pipeline has run at least once, navigate to the environments page under **Pipelines > Environments**. -As the pipeline executes Deploy Boards will clearly mark canary pods, enabling +As the pipeline executes, Deploy Boards clearly mark canary pods, enabling quick and easy insight into the status of each environment and deployment. Canary deployments are marked with a yellow dot in the Deploy Board so that you @@ -68,9 +68,10 @@ can easily notice them.  -### Advanced traffic control with Canary Ingress **(PREMIUM)** +### Advanced traffic control with Canary Ingress -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215501) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215501) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to Core in GitLab 13.7. Canary deployments can be more strategic with [Canary Ingress](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#canary), which is an advanced traffic routing service that controls incoming HTTP @@ -102,21 +103,22 @@ Here's an example setup flow from scratch: #### How to check the current traffic weight on a Canary Ingress -1. Visit [Deploy Board](../../user/project/deploy_boards.md). -1. Open your browser's inspection tool and examine a response from the `environments.json` endpoint. - You can find the current weight under `rollout_status`. +1. Visit the [Deploy Board](../../user/project/deploy_boards.md). +1. View the current weights on the right. -  - - Note that we have [a plan](https://gitlab.com/gitlab-org/gitlab/-/issues/218139) - to visualize this information in a [Deploy Board](../../user/project/deploy_boards.md) - without needing a browser's inspection tool. +  #### How to change the traffic weight on a Canary Ingress -You can change the traffic weight by using [GraphiQL](../../api/graphql/getting_started.md#graphiql) +You can change the traffic weight within your environment's Deploy Board by using [GraphiQL](../../api/graphql/getting_started.md#graphiql), or by sending requests to the [GraphQL API](../../api/graphql/getting_started.md#command-line). +To use your [Deploy Board](../../user/project/deploy_boards.md): + +1. Navigate to **Operations > Environments** for your project. +1. Set the new weight with the dropdown on the right side. +1. Confirm your selection. + Here's an example using [GraphiQL](../../api/graphql/getting_started.md#graphiql): 1. Visit [GraphiQL Explorer](https://gitlab.com/-/graphql-explorer). @@ -135,6 +137,3 @@ Here's an example using [GraphiQL](../../api/graphql/getting_started.md#graphiql 1. If the request succeeds, the `errors` response contains an empty array. GitLab sends a `PATCH` request to your Kubernetes cluster for updating the weight parameter on a Canary Ingress. - -Note that there's [a plan](https://gitlab.com/gitlab-org/gitlab/-/issues/218139) -to control the weight from a [Deploy Board](../../user/project/deploy_boards.md). diff --git a/doc/user/project/ci_cd_for_external_repo.md b/doc/user/project/ci_cd_for_external_repo.md index a92d3a2c308..57747be3859 100644 --- a/doc/user/project/ci_cd_for_external_repo.md +++ b/doc/user/project/ci_cd_for_external_repo.md @@ -3,3 +3,6 @@ redirect_to: '../../ci/ci_cd_for_external_repos/index.md' --- This document was moved to [another location](../../ci/ci_cd_for_external_repos/index.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/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index c3f2b96ce9f..07aa02db2b5 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Adding EKS clusters @@ -10,7 +10,7 @@ GitLab supports adding new and existing EKS clusters. ## EKS requirements -Before creating your first cluster on Amazon EKS with GitLab's integration, make sure the following +Before creating your first cluster on Amazon EKS with the GitLab integration, make sure the following requirements are met: - An [Amazon Web Services](https://aws.amazon.com/) account is set up and you are able to log in. @@ -23,9 +23,9 @@ requirements are met: ### Additional requirements for self-managed instances **(CORE ONLY)** If you are using a self-managed GitLab instance, GitLab must first be configured with a set of -Amazon credentials. These credentials will be used to assume an Amazon IAM role provided by the user +Amazon credentials. These credentials are used to assume an Amazon IAM role provided by the user creating the cluster. Create an IAM user and ensure it has permissions to assume the role(s) that -your users will use to create EKS clusters. +your users need to create EKS clusters. For example, the following policy document allows assuming a role whose name starts with `gitlab-eks-` in account `123456789012`: @@ -60,7 +60,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - Group's **Kubernetes** page, for a group-level cluster. - **Admin Area > Kubernetes**, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. -1. Under the **Create new cluster** tab, click **Amazon EKS**. You will be provided with an +1. Under the **Create new cluster** tab, click **Amazon EKS** to display an `Account ID` and `External ID` needed for later steps. 1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM policy: 1. From the left panel, select **Policies**. @@ -137,9 +137,9 @@ To create and add a new Kubernetes cluster to your project, group, or instance: 1. Click **Next: Tags**, and optionally enter any tags you wish to associate with this role. 1. Click **Next: Review**. 1. Enter a role name and optional description into the fields provided. - 1. Click **Create role**, the new role name will appear at the top. Click on its name and copy the `Role ARN` from the newly created role. + 1. Click **Create role**, the new role name displays at the top. Click on its name and copy the `Role ARN` from the newly created role. 1. In GitLab, enter the copied role ARN into the `Role ARN` field. -1. In the **Cluster Region** field, enter the [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) you plan to use for your new cluster. GitLab will authenticate you have access to this region when authenticating your role. +1. In the **Cluster Region** field, enter the [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) you plan to use for your new cluster. GitLab confirms you have access to this region when authenticating your role. 1. Click **Authenticate with AWS**. 1. Choose your cluster's settings: - **Kubernetes cluster name** - The name you wish to give the cluster. @@ -148,7 +148,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **Service role** - Select the **EKS IAM role** you created earlier to allow Amazon EKS and the Kubernetes control plane to manage AWS resources on your behalf. - NOTE: **Note:** + NOTE: This IAM role is _not_ the IAM role you created in the previous step. It should be the one you created much earlier by following the [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) @@ -158,7 +158,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **VPC** - Select a [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. - **Subnets** - Choose the [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) - in your VPC where your worker nodes will run. You must select at least two. + in your VPC where your worker nodes run. You must select at least two. - **Security group** - Choose the [security group](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) to apply to the EKS-managed Elastic Network Interfaces that are created in your worker node subnets. - **Instance type** - The [instance type](https://aws.amazon.com/ec2/instance-types/) of your worker nodes. @@ -167,11 +167,11 @@ To create and add a new Kubernetes cluster to your project, group, or instance: See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. 1. Finally, click the **Create Kubernetes cluster** button. -After about 10 minutes, your cluster will be ready to go. You can now proceed +After about 10 minutes, your cluster is ready to go. You can now proceed to install some [pre-defined applications](index.md#installing-applications). -NOTE: **Note:** -You will need to add your AWS external ID to the +NOTE: +You must add your AWS external ID to the [IAM Role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-xaccount) to manage your cluster using `kubectl`. @@ -205,7 +205,7 @@ If the `Cluster` resource failed with the error `The provided role doesn't have the Amazon EKS Managed Policies associated with it.`, the role specified in **Role name** is not configured correctly. -NOTE: **Note:** +NOTE: This role should be the role you created by following the [EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) guide. In addition to the policies that guide suggests, you must also include the @@ -219,9 +219,9 @@ For information on adding an existing EKS cluster, see ### Create a default Storage Class Amazon EKS doesn't have a default Storage Class out of the box, which means -requests for persistent volumes will not be automatically fulfilled. As part +requests for persistent volumes are not automatically fulfilled. As part of Auto DevOps, the deployed PostgreSQL instance requests persistent storage, -and without a default storage class it will fail to start. +and without a default storage class it cannot start. If a default Storage Class doesn't already exist and is desired, follow Amazon's [guide on storage classes](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) @@ -239,18 +239,17 @@ to build, test, and deploy the app. [Enable Auto DevOps](../../../topics/autodevops/index.md#at-the-project-level) if not already enabled. If a wildcard DNS entry was created resolving to the Load Balancer, enter it in the `domain` field under the Auto DevOps settings. -Otherwise, the deployed app will not be externally available outside of the cluster. +Otherwise, the deployed app isn't externally available outside of the cluster.  -A new pipeline will automatically be created, which will begin to build, test, -and deploy the app. +GitLab creates a new pipeline, which begins to build, test, and deploy the app. -After the pipeline has finished, your app will be running in EKS and available +After the pipeline has finished, your app runs in EKS, and is available to users. Click on **CI/CD > Environments**.  -You will see a list of the environments and their deploy status, as well as +GitLab displays a list of the environments and their deploy status, as well as options to browse to the app, view monitoring metrics, and even access a shell on the running pod. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 720f9bdf253..e3e6efc887f 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Adding GKE clusters @@ -10,7 +10,7 @@ GitLab supports adding new and existing GKE clusters. ## GKE requirements -Before creating your first cluster on Google GKE with GitLab's integration, make sure the following +Before creating your first cluster on Google GKE with GitLab integration, make sure the following requirements are met: - A [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) @@ -33,7 +33,7 @@ Note the following: created by GitLab are RBAC-enabled. Take a look at the [RBAC section](add_remove_clusters.md#rbac-cluster-resources) for more information. - Starting from [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18341), the - cluster's pod address IP range will be set to /16 instead of the regular /14. /16 is a CIDR + cluster's pod address IP range is set to `/16` instead of the regular `/14`. `/16` is a CIDR notation. - GitLab requires basic authentication enabled and a client certificate issued for the cluster to set up an [initial service account](add_remove_clusters.md#access-controls). In [GitLab versions @@ -57,20 +57,20 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **Kubernetes cluster name** - The name you wish to give the cluster. - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope) to this cluster. - **Google Cloud Platform project** - Choose the project you created in your GCP - console that will host the Kubernetes cluster. Learn more about + console to host the Kubernetes cluster. Learn more about [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). - **Zone** - Choose the [region zone](https://cloud.google.com/compute/docs/regions-zones/) - under which the cluster will be created. + under which to create the cluster. - **Number of nodes** - Enter the number of nodes you wish the cluster to have. - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) - of the Virtual Machine instance that the cluster will be based on. + of the Virtual Machine instance to base the cluster on. - **Enable Cloud Run for Anthos** - Check this if you want to use Cloud Run for Anthos for this cluster. See the [Cloud Run for Anthos section](#cloud-run-for-anthos) for more information. - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. 1. Finally, click the **Create Kubernetes cluster** button. -After a couple of minutes, your cluster will be ready to go. You can now proceed +After a couple of minutes, your cluster is ready. You can now proceed to install some [pre-defined applications](index.md#installing-applications). ### Cloud Run for Anthos @@ -79,7 +79,7 @@ to install some [pre-defined applications](index.md#installing-applications). You can choose to use Cloud Run for Anthos in place of installing Knative and Istio separately after the cluster has been created. This means that Cloud Run -(Knative), Istio, and HTTP Load Balancing will be enabled on the cluster at +(Knative), Istio, and HTTP Load Balancing are enabled on the cluster at create time and cannot be [installed or uninstalled](../../clusters/applications.md) separately. ## Existing GKE cluster diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index c96e38b1dfc..8ee9b1f37dd 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Adding and removing Kubernetes clusters @@ -13,16 +13,16 @@ GitLab offers integrated cluster creation for the following Kubernetes providers GitLab can also integrate with any standard Kubernetes provider, either on-premise or hosted. -NOTE: **Note:** +NOTE: Watch the webcast [Scalable app deployment with GitLab and Google Cloud Platform](https://about.gitlab.com/webcast/scalable-app-deploy/) and learn how to spin up a Kubernetes cluster managed by Google Cloud Platform (GCP) in a few clicks. -TIP: **Tip:** +NOTE: Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign up](https://console.cloud.google.com/freetrial). In partnership with Google, GitLab is able to offer an additional $200 for new GCP -accounts to get started with GitLab's Google Kubernetes Engine Integration. +accounts to get started with the GitLab integration with Google Kubernetes Engine. [Follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) to apply for credit. @@ -260,7 +260,7 @@ To add a Kubernetes cluster to your project, group, or instance: kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password> ``` - NOTE: **Note:** + NOTE: Basic Authentication can be turned on and the password credentials can be obtained using the Google Cloud Console. @@ -295,7 +295,7 @@ To add a Kubernetes cluster to your project, group, or instance: token: <authentication_token> ``` - NOTE: **Note:** + NOTE: For GKE clusters, you need the `container.clusterRoleBindings.create` permission to create a cluster role binding. You can follow the [Google Cloud @@ -330,7 +330,7 @@ integration to work properly.  -CAUTION: **Caution:** +WARNING: Disabling RBAC means that any application running in the cluster, or user who can authenticate to the cluster, has full API access. This is a [security concern](index.md#security-implications), and may not be desirable. diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md index 895b51ea9bb..e38fbb871c1 100644 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ b/doc/user/project/clusters/eks_and_gitlab/index.md @@ -3,3 +3,6 @@ redirect_to: '../add_eks_clusters.md#existing-eks-cluster' --- This document was moved to [another location](../add_eks_clusters.md#existing-eks-cluster). + +<!-- 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/clusters/index.md b/doc/user/project/clusters/index.md index 9273fb7b361..80db1c960db 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Health -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Kubernetes clusters @@ -20,7 +20,7 @@ Using the GitLab project Kubernetes integration, you can: - Detect and [monitor Kubernetes](#monitoring-your-kubernetes-cluster). - Use it with [Auto DevOps](#auto-devops). - Use [Web terminals](#web-terminals). -- Use [Deploy Boards](#deploy-boards). **(PREMIUM)** +- Use [Deploy Boards](#deploy-boards). - Use [Canary Deployments](#canary-deployments). **(PREMIUM)** - Use [deployment variables](#deployment-variables). - Use [role-based or attribute-based access controls](add_remove_clusters.md#access-controls). @@ -45,18 +45,18 @@ versions at any given time. We regularly review the versions we support, and provide a three-month deprecation period before we remove support of a specific version. The range of supported versions is based on the evaluation of: -- Our own needs. - The versions supported by major managed Kubernetes providers. - The versions [supported by the Kubernetes community](https://kubernetes.io/docs/setup/release/version-skew-policy/#supported-versions). GitLab supports the following Kubernetes versions, and you can upgrade your Kubernetes version to any supported version at any time: -- 1.17 -- 1.16 -- 1.15 +- 1.19 (support ends on February 22, 2022) +- 1.18 (support ends on November 22, 2021) +- 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) -- 1.13 (deprecated, support ends on November 22, 2020) Some GitLab features may support versions outside the range provided here. @@ -66,7 +66,7 @@ See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for detail to: - Create a cluster in Google Cloud Platform (GCP) or Amazon Elastic Kubernetes Service - (EKS) using GitLab's UI. + (EKS) using the GitLab UI. - Add an integration to an existing cluster from any Kubernetes platform. ### Multiple Kubernetes clusters @@ -79,8 +79,8 @@ project. That way you can have different clusters for different environments, like dev, staging, production, and so on. Simply add another cluster, like you did the first time, and make sure to -[set an environment scope](#setting-the-environment-scope) that will -differentiate the new cluster with the rest. +[set an environment scope](#setting-the-environment-scope) that +differentiates the new cluster from the rest. #### Setting the environment scope @@ -89,9 +89,9 @@ them with an environment scope. The environment scope associates clusters with [ [environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) work. The default environment scope is `*`, which means all jobs, regardless of their -environment, will use that cluster. Each scope can only be used by a single -cluster in a project, and a validation error will occur if otherwise. -Also, jobs that don't have an environment keyword set will not be able to access any cluster. +environment, use that cluster. Each scope can be used only by a single cluster +in a project, and a validation error occurs if otherwise. Also, jobs that don't +have an environment keyword set can't access any cluster. For example, let's say the following Kubernetes clusters exist in a project: @@ -127,13 +127,13 @@ deploy to production: url: https://example.com/ ``` -The result will then be: +The results: -- The Development cluster details will be available in the `deploy to staging` +- The Development cluster details are available in the `deploy to staging` job. -- The production cluster details will be available in the `deploy to production` +- The production cluster details are available in the `deploy to production` job. -- No cluster details will be available in the `test` job because it doesn't +- No cluster details are available in the `test` job because it doesn't define any environment. ## Configuring your Kubernetes cluster @@ -143,7 +143,7 @@ important considerations for configuring Kubernetes clusters with GitLab. ### Security implications -CAUTION: **Important:** +WARNING: The whole cluster security is based on a model where [developers](../../permissions.md) are trusted, so **only trusted users should be allowed to control your clusters**. @@ -157,15 +157,15 @@ applications running on the cluster. > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 11.5. > - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. -You can choose to allow GitLab to manage your cluster for you. If your cluster is -managed by GitLab, resources for your projects will be automatically created. See the -[Access controls](add_remove_clusters.md#access-controls) section for details on which resources will -be created. +You can choose to allow GitLab to manage your cluster for you. If your cluster +is managed by GitLab, resources for your projects are automatically created. See +the [Access controls](add_remove_clusters.md#access-controls) section for +details about the created resources. -If you choose to manage your own cluster, project-specific resources will not be created -automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you will -need to explicitly provide the `KUBE_NAMESPACE` [deployment variable](#deployment-variables) -that will be used by your deployment jobs, otherwise a namespace will be created for you. +If you choose to manage your own cluster, project-specific resources aren't created +automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you must +explicitly provide the `KUBE_NAMESPACE` [deployment variable](#deployment-variables) +for your deployment jobs to use; otherwise a namespace is created for you. #### Important notes @@ -198,10 +198,10 @@ To clear the cache: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24580) in GitLab 11.8. You do not need to specify a base domain on cluster settings when using GitLab Serverless. The domain in that case -will be specified as part of the Knative installation. See [Installing Applications](#installing-applications). +is specified as part of the Knative installation. See [Installing Applications](#installing-applications). -Specifying a base domain will automatically set `KUBE_INGRESS_BASE_DOMAIN` as an environment variable. -If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain will be used for the different +Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an environment 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. The domain should have a wildcard DNS configured to the Ingress IP address. After Ingress has been installed (see [Installing Applications](#installing-applications)), @@ -224,7 +224,7 @@ Auto DevOps automatically detects, builds, tests, deploys, and monitors your applications. To make full use of Auto DevOps (Auto Deploy, Auto Review Apps, and -Auto Monitoring) you will need the Kubernetes project integration enabled, but +Auto Monitoring) the Kubernetes project integration must be enabled, but Kubernetes clusters can be used without Auto DevOps. [Read more about Auto DevOps](../../../topics/autodevops/index.md) @@ -237,8 +237,8 @@ A Kubernetes cluster can be the destination for a deployment job. If [deployment variables](#deployment-variables) are made available to your job and configuration is not required. You can immediately begin interacting with the cluster from your jobs using tools such as `kubectl` or `helm`. -- You don't use GitLab's cluster integration you can still deploy to your - cluster. However, you will need configure Kubernetes tools yourself +- 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-environment-variables) before you can interact with the cluster from your jobs. @@ -257,14 +257,14 @@ The Kubernetes cluster integration exposes the following GitLab CI/CD build environment to deployment jobs, which are jobs that have [defined a target environment](../../../ci/environments/index.md#defining-environments). -| 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. | -| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `<project_name>-<project_id>`. | -| `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | -| `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | -| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This configuration also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. | +| 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. | +| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `<project_name>-<project_id>`. | +| `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | +| `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | +| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This configuration also embeds the same token defined in `KUBE_TOKEN` so you likely need only this variable. This variable name is also automatically picked up by `kubectl` so you don't need to reference it explicitly if using `kubectl`. | | `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](#base-domain) for more information. | ### Custom namespace @@ -294,7 +294,7 @@ You can customize the deployment namespace in a few ways: When you customize the namespace, existing environments remain linked to their current namespaces until you [clear the cluster cache](#clearing-the-cluster-cache). -CAUTION: **Warning:** +WARNING: By default, anyone who can create a deployment job can access any CI variable within an environment's deployment job. This includes `KUBECONFIG`, which gives access to any secret available to the associated service account in your cluster. @@ -316,9 +316,9 @@ the need to leave GitLab. [Read more about Canary Deployments](../canary_deployments.md) -#### Deploy Boards **(PREMIUM)** +#### Deploy Boards -GitLab's Deploy Boards offer a consolidated view of the current health and +GitLab Deploy Boards offer a consolidated view of the current health and status of each CI [environment](../../../ci/environments/index.md) running on Kubernetes, displaying the status of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the @@ -362,7 +362,7 @@ the deployment job: - A namespace. - A service account. -However, sometimes GitLab can not create them. In such instances, your job will fail with the message: +However, sometimes GitLab can not create them. In such instances, your job can fail with the message: ```plaintext This job failed because the necessary resources were not successfully created. @@ -376,9 +376,9 @@ Reasons for failure include: 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 - `environment:name` set, it will not be passed the Kubernetes credentials. + `environment:name` set, the Kubernetes credentials are not passed to it. -NOTE: **Note:** +NOTE: Project-level clusters upgraded from GitLab 12.0 or older may be configured in a way that causes this error. Ensure you deselect the [GitLab-managed cluster](#gitlab-managed-clusters) option if you want to manage @@ -396,6 +396,6 @@ Automatically detect and monitor Kubernetes metrics. Automatic monitoring of > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Core in 13.2. -When [Prometheus is deployed](#installing-applications), GitLab will automatically monitor the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. +When [Prometheus is deployed](#installing-applications), GitLab monitors the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start.  diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 2e224208eb8..2523dc3e0a2 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Health -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Kubernetes Logs diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index c1e4e821efd..332c1f35d89 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Runbooks @@ -25,7 +25,7 @@ pre-written code blocks or database queries against a given environment. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45912) in GitLab 11.4. -The JupyterHub app offered via GitLab’s Kubernetes integration now ships +The JupyterHub app offered via the GitLab Kubernetes integration now ships with Nurtch’s Rubix library, providing a simple way to create DevOps runbooks. A sample runbook is provided, showcasing common operations. While Rubix makes it simple to create common Kubernetes and AWS workflows, you can @@ -37,11 +37,11 @@ for an overview of how this is accomplished in GitLab! ## Requirements -To create an executable runbook, you will need: +To create an executable runbook, you need: - **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications. The simplest way to get started is to add a cluster using one - of [GitLab's integrations](../add_remove_clusters.md#create-new-cluster). + of the [GitLab integrations](../add_remove_clusters.md#create-new-cluster). - **Ingress** - Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications. - **JupyterHub** - [JupyterHub](https://jupyterhub.readthedocs.io/) is a multi-user @@ -71,7 +71,7 @@ the components outlined above and the pre-loaded demo runbook.  1. After Ingress has been installed successfully, click the **Install** button next - to the **JupyterHub** application. You will need the **Jupyter Hostname** provided + to the **JupyterHub** application. You need the **Jupyter Hostname** provided here in the next step.  @@ -84,8 +84,8 @@ the components outlined above and the pre-loaded demo runbook.  -1. Click **Authorize**, and you will be redirected to the JupyterHub application. -1. Click **Start My Server**, and the server will start in a few seconds. +1. Click **Authorize**, and GitLab redirects you to the JupyterHub application. +1. Click **Start My Server** to start the server in a few seconds. 1. To configure the runbook's access to your GitLab project, you must enter your [GitLab Access Token](../../../profile/personal_access_tokens.md) and your Project ID in the **Setup** section of the demo runbook: diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md index 2d74f67ba35..fa80bd6423b 100644 --- a/doc/user/project/clusters/securing.md +++ b/doc/user/project/clusters/securing.md @@ -1,7 +1,7 @@ --- stage: Protect group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Securing your deployed applications @@ -40,7 +40,7 @@ Minimum requirements (depending on the GitLab Manage Application you want to ins ### Understanding how GitLab Managed Apps are installed -NOTE: **Note:** +NOTE: These diagrams use the term _Kubernetes_ for simplicity. In practice, Sidekiq connects to a Helm command runner pod in the cluster. diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 0de0fd38336..a52d3400aa2 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Deploying AWS Lambda function using GitLab CI/CD @@ -29,7 +29,7 @@ Alternatively, you can quickly [create a new project with a template](../../../. ### Example -In the following example, you will: +This example shows you how to: 1. Create a basic AWS Lambda Node.js function. 1. Link the function to an API Gateway `GET` endpoint. @@ -49,7 +49,7 @@ Lets take it step by step. #### Creating a Lambda handler function -Your Lambda function will be the primary handler of requests. In this case we will create a very simple Node.js `hello` function: +Your Lambda function is the primary handler of requests. In this case, create a very simple Node.js `hello` function: ```javascript 'use strict'; @@ -72,13 +72,13 @@ Place this code in the file `src/handler.js`. `src` is the standard location for serverless functions, but is customizable should you desire that. -In our case, `module.exports.hello` defines the `hello` handler that will be referenced later in the `serverless.yml` +In our case, `module.exports.hello` defines the `hello` handler to reference later in the `serverless.yml`. You can learn more about the AWS Lambda Node.js function handler and all its various options here: <https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html> #### Creating a `serverless.yml` file -In the root of your project, create a `serverless.yml` file that will contain configuration specifics for the Serverless Framework. +In the root of your project, create a `serverless.yml` file containing configuration specifics for the Serverless Framework. Put the following code in the file: @@ -97,9 +97,9 @@ functions: Our function contains a handler and a event. -The handler definition will provision the Lambda function using the source code located `src/handler.hello`. +The handler definition provisions the Lambda function using the source code located `src/handler.hello`. -The `events` declaration will create a AWS API Gateway `GET` endpoint to receive external requests and hand them over to the Lambda function via a service integration. +The `events` declaration creates an AWS API Gateway `GET` endpoint to receive external requests and hand them over to the Lambda function via a service integration. You can read more about the [available properties and additional configuration possibilities](https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml/) of the Serverless Framework. @@ -141,10 +141,10 @@ For more information please see [Create a custom variable in the UI](../../../.. #### Deploying your function -`git push` the changes to your GitLab repository and the GitLab build pipeline will automatically deploy your function. +`git push` the changes to your GitLab repository and the GitLab build pipeline deploys your function. -In your GitLab deploy stage log, there will be output containing your AWS Lambda endpoint URL. -The log line will look similar to this: +Your GitLab deploy stage log contains output containing your AWS Lambda endpoint URL, +with log lines similar to this: ```plaintext endpoints: @@ -157,7 +157,7 @@ Running the following `curl` command should trigger your function. Your URL should be the one retrieved from the GitLab deploy stage log: ```shell -curl https://u768nzby1j.execute-api.us-east-1.amazonaws.com/production/hello +curl "https://u768nzby1j.execute-api.us-east-1.amazonaws.com/production/hello" ``` That should output: @@ -200,7 +200,7 @@ The `serverless-offline` plugin allows to run your code locally. To run your cod Running the following `curl` command should trigger your function. ```shell -curl http://localhost:3000/hello +curl "http://localhost:3000/hello" ``` It should output: @@ -227,9 +227,9 @@ provider: ``` From there, you can reference them in your functions as well. -Remember to add `A_VARIABLE` to your GitLab CI/CD variables under **Settings > CI/CD > Variables**, and it will get picked up and deployed with your function. +Remember to add `A_VARIABLE` to your GitLab CI/CD variables under **Settings > CI/CD > Variables** to be picked up and deployed with your function. -NOTE: **Note:** +NOTE: Anyone with access to the AWS environment may be able to see the values of those variables persisted in the lambda definition. @@ -309,7 +309,7 @@ GitLab allows developers to build and deploy serverless applications using the c ### Example -In the following example, you will: +This example shows you how to: - Install SAM CLI. - Create a sample SAM application including a Lambda function and API Gateway. @@ -414,8 +414,8 @@ Let’s examine the configuration file more closely: ### Deploying your application -Push changes to your GitLab repository and the GitLab build pipeline will automatically -deploy your application. If your: +Push changes to your GitLab repository and the GitLab build pipeline +deploys your application. If your: - Build and deploy are successful, [test your deployed application](#testing-the-deployed-application). - Build fails, look at the build log to see why the build failed. Some common reasons @@ -444,7 +444,7 @@ To test the application you deployed, please go to the build log and follow the 1. Use curl to test the API. For example: ```shell - curl https://py4rg7qtlg.execute-api.us-east-1.amazonaws.com/Prod/hello/ + curl "https://py4rg7qtlg.execute-api.us-east-1.amazonaws.com/Prod/hello/" ``` Output should be: @@ -496,7 +496,7 @@ listening on `localhost:3000`. Call the `hello` API by running: ```shell -curl http://127.0.0.1:3000/hello +curl "http://127.0.0.1:3000/hello" ``` Output again should be: diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 603c4bd73b1..fcbf85121b2 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -1,15 +1,15 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Serverless > Introduced in GitLab 11.5. -CAUTION: **Caution:** -Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/#alpha). +WARNING: +Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). ## Overview @@ -39,9 +39,9 @@ With GitLab Serverless, you can deploy both functions-as-a-service (FaaS) and se ## Prerequisites -To run Knative on GitLab, you will need: +To run Knative on GitLab, you need: -1. **Existing GitLab project:** You will need a GitLab project to associate all resources. The simplest way to get started: +1. **Existing GitLab project:** You need a GitLab project to associate all resources. The simplest way to get started: - If you are planning on [deploying functions](#deploying-functions), clone the [functions example project](https://gitlab.com/knative-examples/functions) to get started. @@ -49,21 +49,21 @@ To run Knative on GitLab, you will need: clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. 1. **Kubernetes Cluster:** An RBAC-enabled Kubernetes cluster is required to deploy Knative. - The simplest way to get started is to add a cluster using GitLab's [GKE integration](../add_remove_clusters.md). + The simplest way to get started is to add a cluster using the GitLab [GKE integration](../add_remove_clusters.md). The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. -1. **GitLab Runner:** A runner is required to run the CI jobs that will deploy serverless +1. **GitLab Runner:** A runner is required to run the CI jobs that deploy serverless applications or functions onto your cluster. You can install GitLab Runner onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information. -1. **Domain Name:** Knative will provide its own load balancer using Istio. It will provide an - external IP address or hostname for all the applications served by Knative. You will be prompted to enter a - wildcard domain where your applications will be served. Configure your DNS server to use the +1. **Domain Name:** Knative provides its own load balancer using Istio, and an + external IP address or hostname for all the applications served by Knative. Enter a + wildcard domain to serve your applications. Configure your DNS server to use the external IP address or hostname for that domain. 1. **`.gitlab-ci.yml`:** GitLab uses [Kaniko](https://github.com/GoogleContainerTools/kaniko) to build the application. We also use [GitLab Knative tool](https://gitlab.com/gitlab-org/gitlabktl) CLI to simplify the deployment of services and functions to Knative. 1. **`serverless.yml`** (for [functions only](#deploying-functions)): When using serverless to deploy functions, the `serverless.yml` file - will contain the information for all the functions being hosted in the repository as well as a reference to the - runtime being used. + contains the information for all the functions being hosted in the repository as well as a reference + to the runtime being used. 1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications)): Knative requires a `Dockerfile` in order to build your applications. It should be included at the root of your project's repository and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions @@ -73,7 +73,7 @@ To run Knative on GitLab, you will need: 1. **Logging** (optional): Configuring logging allows you to view and search request logs for your serverless function/application. See [Configuring logging](#configuring-logging) for more information. -## Installing Knative via GitLab's Kubernetes integration +## Installing Knative via the GitLab Kubernetes integration The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. **RBAC must be enabled.** @@ -87,12 +87,12 @@ memory. **RBAC must be enabled.** 1. After the Knative installation has finished, you can wait for the IP address or hostname to be displayed in the **Knative Endpoint** field or [retrieve the Istio Ingress Endpoint manually](../../../clusters/applications.md#determining-the-external-endpoint-manually). - NOTE: **Note:** + 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/). -1. The Ingress is now available at this address and will route incoming requests to the proper service based on the DNS +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, if your Knative base domain is `knative.info` then you need to create an A record or CNAME record with domain `*.knative.info` pointing the IP address or hostname of the Ingress. @@ -107,7 +107,7 @@ on a given project, but not both. The current implementation makes use of a > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58941) in GitLab 12.0. -The _invocations_ monitoring feature of GitLab serverless won't work when +The _invocations_ monitoring feature of GitLab serverless is unavailable when adding an existing installation of Knative. It's also possible to use GitLab Serverless with an existing Kubernetes cluster @@ -121,9 +121,9 @@ which already has Knative installed. You must do the following: - For a non-GitLab managed cluster, ensure that the service account for the token provided can manage resources in the `serving.knative.dev` API group. - For a GitLab managed cluster, if you added the cluster in [GitLab 12.1 or later](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30235), - then GitLab will already have the required access and you can proceed to the next step. + then GitLab already has the required access and you can proceed to the next step. - Otherwise, you need to manually grant GitLab's service account the ability to manage + Otherwise, you need to manually grant the GitLab service account the ability to manage resources in the `serving.knative.dev` API group. Since every GitLab service account has the `edit` cluster role, the simplest way to do this is with an [aggregated ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles) @@ -234,12 +234,12 @@ Follow these steps to deploy a function using the Node.js runtime to your Knative instance (you can skip these steps if you've cloned the example project): -1. Create a directory that will house the function. In this example we will +1. Create a directory to house the function. In this example we will create a directory called `echo` at the root of the project. -1. Create the file that will contain the function code. In this example, our file is called `echo.js` and is located inside the `echo` directory. If your project is: +1. Create the file to contain the function code. In this example, our file is called `echo.js` and is located inside the `echo` directory. If your project is: - Public, continue to the next step. - - Private, you will need to [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. + - Private, you must [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. 1. `.gitlab-ci.yml`: this defines a pipeline used to deploy your functions. It must be included at the root of your repository: @@ -304,7 +304,7 @@ Explanation of the fields used above: | Parameter | Description | |-----------|-------------| -| `service` | Name for the Knative service which will serve the function. | +| `service` | Name for the Knative service which serves the function. | | `description` | A short description of the `service`. | ### `provider` @@ -349,9 +349,9 @@ The optional `runtime` parameter can refer to one of the following runtime alias | `openfaas/classic/ruby` | OpenFaaS | After the `gitlab-ci.yml` template has been added and the `serverless.yml` file -has been created, pushing a commit to your project will result in a CI pipeline -being executed which will deploy each function as a Knative service. Once the -deploy stage has finished, additional details for the function will appear +has been created, pushing a commit to your project results in a CI pipeline +being executed which deploys each function as a Knative service. After the +deploy stage has finished, additional details for the function display under **Operations > Serverless**.  @@ -376,7 +376,7 @@ The sample function can now be triggered from any HTTP client using a simple `PO --header "Content-Type: application/json" \ --request POST \ --data '{"GitLab":"FaaS"}' \ - http://functions-echo.functions-1.functions.example.com/ + "http://functions-echo.functions-1.functions.example.com/" ``` 1. Using a web-based tool (such as Postman or Restlet) @@ -443,14 +443,13 @@ To run a function locally: 1. Invoke your function: ```shell - curl http://localhost:8080 + curl "http://localhost:8080" ``` ## Deploying Serverless applications > Introduced in GitLab 11.5. -12345678901234567890123456789012345678901234567890123456789012345678901234567890 Serverless applications are an alternative to [serverless functions](#deploying-functions). They're useful in scenarios where an existing runtime does not meet the needs of an application, such as one written in a language that has no runtime available. @@ -482,7 +481,7 @@ A `serverless.yml` file is not required when deploying serverless applications. ### Deploy the application with Knative -With all the pieces in place, the next time a CI pipeline runs, the Knative application will be deployed. Navigate to +With all the pieces in place, the next time a CI pipeline runs the Knative application deploys. Navigate to **CI/CD > Pipelines** and click the most recent pipeline. ### Function details @@ -498,13 +497,13 @@ rows to bring up the function details page.  -The pod count will give you the number of pods running the serverless function instances on a given cluster. +The pod count gives you the number of pods running the serverless function instances on a given cluster. For the Knative function invocations to appear, [Prometheus must be installed](../index.md#installing-applications). Once Prometheus is installed, a message may appear indicating that the metrics data _is -loading or is not available at this time._ It will appear upon the first access of the +loading or is not available at this time._ It appears upon the first access of the page, but should go away after a few seconds. If the message does not disappear, then it is possible that GitLab is unable to connect to the Prometheus instance running on the cluster. @@ -558,7 +557,7 @@ Or: ## Enabling TLS for Knative services -By default, a GitLab serverless deployment will be served over `http`. To serve +By default, a GitLab serverless deployment is served over `http`. To serve over `https`, you must manually obtain and install TLS certificates. 12345678901234567890123456789012345678901234567890123456789012345678901234567890 @@ -647,7 +646,7 @@ or with other versions of Python. ``` 1. Create certificate and private key files. Using the contents of the files - returned by Certbot, we'll create two files in order to create the + returned by Certbot, create two files in order to create the Kubernetes secret: Run the following command to see the contents of `fullchain.pem`: @@ -767,7 +766,7 @@ or with other versions of Python. 1. Create a Kubernetes secret to hold your TLS certificate, `cert.pem`, and the private key `cert.pk`: - NOTE: **Note:** + 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). @@ -828,8 +827,8 @@ or with other versions of Python. ``` After your changes are running on your Knative cluster, you can begin using the HTTPS protocol for secure access your deployed Knative services. - In the event a mistake is made during this process and you need to update the cert, you will need to edit the gateway `knative-ingress-gateway` - to switch back to `PASSTHROUGH` mode. Once corrections are made, edit the file again so the gateway will use the new certificates. + In the event a mistake is made during this process and you need to update the cert, you must edit the gateway `knative-ingress-gateway` + to switch back to `PASSTHROUGH` mode. Once corrections are made, edit the file again so the gateway uses the new certificates. ## Using an older version of `gitlabktl` diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index 5f96f65ea06..19dc3588162 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 37ebef3a26e..d0e89400d88 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -112,7 +112,7 @@ in the `.gitignore` file followed by one or more of: - A user's `@username`. - A user's email address. - The `@name` of one or more groups that should be owners of the file. -- Lines starting with `#` are escaped. +- Lines starting with `#` are ignored. The order in which the paths are defined is significant: the last pattern that matches a given path will be used to find the code owners. diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index 91c9d3171dc..17e86b6d7e8 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -3,3 +3,6 @@ redirect_to: '../packages/container_registry/index.md' --- This document was moved to [another location](../packages/container_registry/index.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/cycle_analytics.md b/doc/user/project/cycle_analytics.md index 9d1cc508f63..5c235f6708b 100644 --- a/doc/user/project/cycle_analytics.md +++ b/doc/user/project/cycle_analytics.md @@ -3,3 +3,6 @@ redirect_to: '../analytics/value_stream_analytics.md' --- This document was moved to [another location](../analytics/value_stream_analytics.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/deploy_boards.md b/doc/user/project/deploy_boards.md index 2bf35b48547..7546556a7c0 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -1,15 +1,16 @@ --- stage: Release -group: Progressive Delivery -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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, reference --- -# Deploy Boards **(PREMIUM)** +# Deploy Boards **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. +> - [Moved](<https://gitlab.com/gitlab-org/gitlab/-/issues/212320>) to GitLab Core in 13.7. -GitLab's Deploy Boards offer a consolidated view of the current health and +GitLab Deploy Boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status 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 @@ -74,7 +75,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ 1. Have a Kubernetes cluster up and running. - NOTE: **Running on OpenShift:** + NOTE: If you are using OpenShift, ensure that you're using the `Deployment` resource instead of `DeploymentConfiguration`. Otherwise, the Deploy Boards won't render correctly. For more information, read the @@ -98,7 +99,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ Kubernetes as well. The image below demonstrates how this is shown inside Kubernetes. - NOTE: **Note:** + NOTE: Matching based on the Kubernetes `app` label was removed in [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/14020). To migrate, please apply the required annotations (see above) and @@ -143,7 +144,7 @@ spec: The annotations will be applied to the deployments, replica sets, and pods. By changing the number of replicas, like `kubectl scale --replicas=3 deploy APPLICATION_NAME -n ${KUBE_NAMESPACE}`, you can follow the instances' pods from the board. -NOTE: **Note:** +NOTE: The YAML file is static. If you apply it using `kubectl apply`, you must manually provide the project and environment slugs, or create a script to replace the variables in the YAML before applying. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 4f344554016..39b790544c1 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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, reference --- @@ -27,7 +27,7 @@ repository in automation, it's a simple solution. A drawback is that your repository could become vulnerable if a remote machine is compromised by a hacker. You should limit access to the remote machine before a deploy key is -enabled on your repository. A good rule to follow is to access only to trusted users, +enabled on your repository. A good rule to follow is to provide access only to trusted users, and make sure that the allowed users have [maintainer permissions or higher](../../permissions.md) in the GitLab project. @@ -108,7 +108,7 @@ keys that were [made available to your entire GitLab instance](#public-deploy-ke After a key is added, you can edit it to update its title, or switch between `read-only` and `read-write` access. -NOTE: **Note:** +NOTE: If you have enabled a privately or publicly accessible or deploy key for your project, and if you then update the access level for this key from `read-only` to `read-write`, the change will be only for the **current project**. @@ -134,7 +134,7 @@ Instance administrators can add public deploy keys: After adding a key, it will be available to any shared systems. Project maintainers or higher can [authorize a public deploy key](#project-deploy-keys) to start using it with the project. -NOTE: **Note:** +NOTE: The **Publicly accessible deploy keys** tab within Project's CI/CD settings only appears if there is at least one Public deploy key configured. @@ -146,7 +146,7 @@ When creating a Public deploy key, determine whether or not it can be defined fo very narrow usage, such as just a specific service, or if it needs to be defined for broader usage, such as full `read-write` access for all services. -CAUTION: **Warning:** +WARNING: Adding a public deploy key does not immediately expose any repository to it. Public deploy keys enable access from other systems, but access is not given to any project until a project maintainer chooses to make use of it. diff --git a/doc/user/project/deploy_tokens/img/deploy_tokens.png b/doc/user/project/deploy_tokens/img/deploy_tokens.png Binary files differdeleted file mode 100644 index 1981b0747bf..00000000000 --- a/doc/user/project/deploy_tokens/img/deploy_tokens.png +++ /dev/null diff --git a/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png b/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png Binary files differnew file mode 100644 index 00000000000..83f59b8f6f0 --- /dev/null +++ b/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 1ac528ca4ae..ac19c44c58a 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 --- @@ -18,6 +18,8 @@ container registry images of a project without having a user and a password. 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) instead. @@ -36,7 +38,7 @@ project. Alternatively, you can also create [group-scoped deploy tokens](#group- 1. Save the deploy token somewhere safe. After you leave or refresh the page, **you won't be able to access it again**. - + ## Deploy token expiration @@ -91,7 +93,7 @@ To read the container registry images, you'll need to: 1. Create a Deploy Token with `read_registry` as a scope. 1. Take note of your `username` and `token`. -1. Sign in to GitLab’s Container Registry using the deploy token: +1. Sign in to the GitLab Container Registry using the deploy token: ```shell docker login -u <username> -p <deploy_token> registry.example.com @@ -108,7 +110,7 @@ To push the container registry images, you'll need to: 1. Create a Deploy Token with `write_registry` as a scope. 1. Take note of your `username` and `token`. -1. Sign in to GitLab’s Container Registry using the deploy token: +1. Sign in to the GitLab Container Registry using the deploy token: ```shell docker login -u <username> -p <deploy_token> registry.example.com @@ -149,6 +151,9 @@ belong either to the specific group or to one of its subgroups. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Group Deploy Tokens](https://youtu.be/8kxTJvaD9ks). +The Group Deploy Tokens UI is now accessible under **Settings > Repository**, +not **Settings > CI/CD** as indicated in the video. + To use a group deploy token: 1. [Create](#creating-a-deploy-token) a deploy token for a group. @@ -174,7 +179,7 @@ those variables: docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY ``` -NOTE: **Note:** +NOTE: The special handling for the `gitlab-deploy-token` deploy token is not currently implemented for group deploy tokens. For the deploy token to be available for CI/CD jobs, it must be created at the project level. For details, see diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 4c14251cfa5..db2631f9596 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Description templates @@ -26,7 +26,7 @@ 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 -templates of the default branch will be taken into account. +templates of the default branch are taken into account. ## Use-cases @@ -53,7 +53,7 @@ To create a Markdown file: example `feature_request.md` or `Feature Request.md`. 1. Commit and push to your default branch. -If you don't have a `.gitlab/issue_templates` directory in your repository, you'll need to create it. +If you don't have a `.gitlab/issue_templates` directory in your repository, you need to create it. To create the `.gitlab/issue_templates` directory: @@ -74,12 +74,12 @@ push to your default branch. ## Using the templates Let's take for example that you've created the file `.gitlab/issue_templates/Bug.md`. -This will enable the `Bug` dropdown option when creating or editing issues. When -`Bug` is selected, the content from the `Bug.md` template file will be copied -to the issue description field. The 'Reset template' button will discard any -changes you made after picking the template and return it to its initial status. +This enables the `Bug` dropdown option when creating or editing issues. When +`Bug` is selected, the content from the `Bug.md` template file is copied +to the issue description field. The **Reset template** button discards any +changes you made after picking the template and returns it to its initial status. -TIP: **Tip:** +NOTE: You can create short-cut links to create an issue using a designated template. For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`.  @@ -92,7 +92,7 @@ You can create short-cut links to create an issue using a designated template. F The visibility of issues and/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 won't show. This is the default behavior so in most cases +template text areas don't show. This is the default behavior, so in most cases you should be fine. 1. Go to your project's **Settings**. @@ -108,7 +108,7 @@ you should be fine.  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 will be +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). ## Description template example @@ -117,9 +117,9 @@ We make use of Description Templates for Issues and Merge Requests within the Gi Edition project. Please refer to the [`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab) for some examples. -TIP: **Tip:** +NOTE: It's possible to use [quick actions](quick_actions.md) within description templates to quickly add -labels, assignees, and milestones. The quick actions will only be executed if the user submitting +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: diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 46c2e211d57..49918b8f023 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -152,7 +152,7 @@ git lfs unlock --id=123 --force You can normally push files to GitLab whether they're locked or unlocked. -NOTE: **Note:** +NOTE: Although multi-branch file locks can be created and managed through the Git LFS command line interface, file locks can be created for any file. @@ -175,7 +175,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: **Note:** +NOTE: When you rename an exclusively-locked file, the lock is lost. You'll have to lock it again to keep it locked. diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 577f0f1f754..459abea455b 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/user/project/gpg_signed_commits/index.md b/doc/user/project/gpg_signed_commits/index.md index bd9a5313489..206013210a0 100644 --- a/doc/user/project/gpg_signed_commits/index.md +++ b/doc/user/project/gpg_signed_commits/index.md @@ -3,3 +3,6 @@ redirect_to: '../repository/gpg_signed_commits/index.md' --- This document was moved to [another location](../repository/gpg_signed_commits/index.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/highlighting.md b/doc/user/project/highlighting.md index 5f7c754ec75..1d92e32e071 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -9,7 +9,7 @@ type: reference GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It will try to guess what language to use based on the file extension, which most of the time is sufficient. -NOTE: **Note:** +NOTE: The [Web IDE](web_ide/index.md) and [Snippets](../snippets.md) use [Monaco Editor](https://microsoft.github.io/monaco-editor/) for text editing, which internally uses the [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for syntax highlighting. @@ -28,7 +28,7 @@ The paths here are simply Git's built-in [`.gitattributes` interface](https://gi /Nicefile gitlab-language=ruby ``` -To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shenanigans are available through CGI options, such as: +To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shenanigans are available through common gateway interface (CGI) options, such as: ``` conf # json with erb in it @@ -40,5 +40,5 @@ To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shen Please note that these configurations will only take effect when the `.gitattributes` file is in your default branch (usually `master`). -NOTE: **Note:** +NOTE: The Web IDE does not support `.gitattribute` files, but it's [planned for a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/22014). diff --git a/doc/user/project/img/canary_weight.png b/doc/user/project/img/canary_weight.png Binary files differnew file mode 100644 index 00000000000..e6544358c15 --- /dev/null +++ b/doc/user/project/img/canary_weight.png diff --git a/doc/user/project/img/issue_board_default_lists_v13_4.png b/doc/user/project/img/issue_board_default_lists_v13_4.png Binary files differdeleted file mode 100644 index 23cdc9b4e22..00000000000 --- a/doc/user/project/img/issue_board_default_lists_v13_4.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_add_issues_modal_v13_6.png b/doc/user/project/img/issue_boards_add_issues_modal_v13_6.png Binary files differdeleted file mode 100644 index a138efc9c1c..00000000000 --- a/doc/user/project/img/issue_boards_add_issues_modal_v13_6.png +++ /dev/null diff --git a/doc/user/project/img/protected_branches_deploy_keys_v13_5.png b/doc/user/project/img/protected_branches_deploy_keys_v13_5.png Binary files differnew file mode 100644 index 00000000000..6eda7a671b2 --- /dev/null +++ b/doc/user/project/img/protected_branches_deploy_keys_v13_5.png diff --git a/doc/user/project/img/rollout_status_canary_ingress.png b/doc/user/project/img/rollout_status_canary_ingress.png Binary files differdeleted file mode 100644 index fb59ba31615..00000000000 --- a/doc/user/project/img/rollout_status_canary_ingress.png +++ /dev/null diff --git a/doc/user/project/img/service_desk_issue_tracker.png b/doc/user/project/img/service_desk_issue_tracker.png Binary files differindex 02d18c9debb..0fde4c182cf 100644 --- a/doc/user/project/img/service_desk_issue_tracker.png +++ b/doc/user/project/img/service_desk_issue_tracker.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 56266718d12..6f274dd12a2 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -2,12 +2,12 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Import your project from Bitbucket Cloud to GitLab -NOTE: **Note:** +NOTE: The Bitbucket Cloud importer works only with Bitbucket.org, not with Bitbucket Server (aka Stash). If you are trying to import projects from Bitbucket Server, use [the Bitbucket Server importer](bitbucket_server.md). @@ -38,10 +38,10 @@ to enable this if not already. ## How it works When issues/pull requests are being imported, the Bitbucket importer tries to find -the Bitbucket author/assignee in GitLab's database using the Bitbucket `nickname`. +the Bitbucket author/assignee in the GitLab database using the Bitbucket `nickname`. For this to work, the Bitbucket author/assignee should have signed in beforehand in GitLab and **associated their Bitbucket account**. Their `nickname` must also match their Bitbucket -`username.`. If the user is not found in GitLab's database, the project creator +`username.`. If the user is not found in the GitLab database, the project creator (most of the times the current user that started the import process) is set as the author, but a reference on the issue about the original Bitbucket author is kept. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index ac5be2b46a4..bb2256c9464 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -2,14 +2,14 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Import your project from Bitbucket Server to GitLab > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2. -NOTE: **Note:** +NOTE: The Bitbucket Server importer does not work with [Bitbucket Cloud](https://bitbucket.org). Use the [Bitbucket Cloud importer](bitbucket.md) for that. @@ -70,7 +70,7 @@ namespace that started the import process. > - It's not recommended for production use. > - To use it in GitLab self-managed instances, ask a GitLab administrator to enable it. -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. If you've enabled this feature, the importer tries to find a user in the GitLab user database with diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index a825084dd1a..7e07ca6f865 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -2,12 +2,12 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Migrating from ClearCase -[ClearCase](https://www.ibm.com/us-en/marketplace/rational-clearcase) is a set of +[ClearCase](https://www.ibm.com/products/rational-clearcase) is a set of tools developed by IBM which also include a centralized version control system similar to Git. diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 2957b33c20e..82ff889c043 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Migrating from CVS @@ -69,7 +69,8 @@ Migrating to Git/GitLab will benefit you: Here's a few links to get you started with the migration: -- [Migrate using the `cvs-fast-export` tool](http://www.catb.org/~esr/reposurgeon/dvcs-migration-guide.html) ([_source code_](https://gitlab.com/esr/cvs-fast-export)) +- [Migrate using the `cvs-fast-export` tool](https://gitlab.com/esr/cvs-fast-export) - [Stack Overflow post on importing the CVS repo](https://stackoverflow.com/a/11490134/974710) - [Convert a CVS repository to Git](https://www.techrepublic.com/blog/linux-and-open-source/convert-cvs-repositories-to-git/) - [Man page of the `git-cvsimport` tool](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-cvsimport.html) +- [Migrate using `reposurgeon`](http://www.catb.org/~esr/reposurgeon/repository-editing.html#conversion) diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 149b5d1913c..1371ca57bc9 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Import your project from FogBugz to GitLab diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index 2d0caa7d46e..38679914a9d 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Gemnasium **(ULTIMATE)** @@ -66,19 +66,19 @@ GitHub.com or GitHub Enterprise repository. This will automatically prompt GitLab CI/CD to run whenever code is pushed to GitHub and post CI/CD results back to both GitLab and GitHub when completed. -1. Create a new project, and select the "CI/CD for external repo" tab: +1. Create a new project, and select "CI/CD for external repo": -  +  1. Use the "GitHub" button to connect your repositories. -  +  1. Select the project(s) to be set up with GitLab CI/CD and chose "Connect". -  +  - Once the configuration is done, you may click on your new + After the configuration is done, you may click on your new project on GitLab.  @@ -107,7 +107,7 @@ back to both GitLab and GitHub when completed.  -NOTE: **Note:** +NOTE: If you don't commit very often to your project, you may want to use [scheduled pipelines](../../../ci/pipelines/schedules.md) to run the job on a regular basis. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 81ab16590dc..26e5a86b808 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Import your project from Gitea to GitLab @@ -11,7 +11,7 @@ Import your projects from Gitea to GitLab with minimal effort. ## Overview -NOTE: **Note:** +NOTE: This requires Gitea `v1.0.0` or newer. - At its current state, Gitea importer can import: @@ -27,7 +27,7 @@ This requires Gitea `v1.0.0` or newer. ## How it works Since Gitea is currently not an OAuth provider, author/assignee cannot be mapped -to users in your GitLab's instance. This means that the project creator (most of +to users in your GitLab instance. This means that the project creator (most of the times the current user that started the import process) is set as the author, but a reference on the issue about the original Gitea author is kept. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 6c0105aaded..8b6d86b14c9 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Import your project from GitHub to GitLab @@ -23,6 +23,8 @@ The following aspects of a project are imported: - Labels (GitLab.com & 8.7+) - Release note descriptions (GitLab.com & 8.12+) - Pull request review comments (GitLab.com & 10.2+) +- Pull request reviews (GitLab.com & 13.7+) +- Pull request "merged by" information (GitLab.com & 13.7+) - Regular issue and pull request comments - [Git Large File Storage (LFS) Objects](../../../topics/git/lfs/index.md) @@ -59,11 +61,11 @@ For this association to succeed, each GitHub author and assignee in the reposito 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 - [primary email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address) - that matches their GitLab account's email address. +- 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) + on their profile that matches their GitLab account's email address. -If a user referenced in the project is not found in GitLab's database, the project creator (typically the user +If a user referenced in the project is not found in the GitLab database, the project creator (typically the user that initiated the import process) is set as the author/assignee, but a note on the issue mentioning the original GitHub author is added. @@ -89,24 +91,24 @@ 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 [public email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address) of the GitHub user +- 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 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. -NOTE: **Note:** +NOTE: If you are using a self-managed GitLab instance or if you are importing from GitHub Enterprise, this process requires that you have configured [GitHub integration](../../../integration/github.md). 1. From the top navigation bar, click **+** and select **New project**. 1. Select the **Import project** tab and then select **GitHub**. 1. Select the first button to **List your GitHub repositories**. You are redirected to a page on [GitHub](https://github.com) to authorize the GitLab application. -1. Click **Authorize GitlabHQ**. You are redirected back to GitLab's Import page and all of your GitHub repositories are listed. +1. Click **Authorize GitlabHQ**. You are redirected back to the GitLab Import page and all of your GitHub repositories are listed. 1. Continue on to [selecting which repositories to import](#selecting-which-repositories-to-import). ### Using a GitHub token -NOTE: **Note:** +NOTE: Using a personal access token to import projects is not recommended. If you are a GitLab.com user, you can use a personal access token to import your project from GitHub, but this method cannot associate all user activity (such as issues and pull requests) with matching GitLab users. @@ -154,8 +156,8 @@ of the above are automatically configured. **(PREMIUM)** ## Improving the speed of imports on self-managed instances -NOTE: **Note:** -Admin access to the GitLab server is required. +NOTE: +Administrator access to the GitLab server is required. For large projects it may take a while to import all data. To reduce the time necessary, you can increase the number of Sidekiq workers that process the following queues: diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 6c622ece4ac..add457c217e 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 importing from GitLab.com to your private GitLab instance @@ -13,7 +13,7 @@ mind that it is possible only if GitLab.com integration is enabled on your GitLa To get to the importer page you need to go to "New project" page. -NOTE: **Note:** +NOTE: If you are interested in importing Wiki and Merge Request data to your new instance, you'll need to follow the instructions for [exporting a project](../settings/import_export.md#exporting-a-project-and-its-data) diff --git a/doc/user/project/import/img/gemnasium/connect_github.png b/doc/user/project/import/img/gemnasium/connect_github.png Binary files differdeleted file mode 100644 index fae62e8d840..00000000000 --- a/doc/user/project/import/img/gemnasium/connect_github.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/connect_github_v13_5.png b/doc/user/project/import/img/gemnasium/connect_github_v13_5.png Binary files differnew file mode 100644 index 00000000000..575d257a213 --- /dev/null +++ b/doc/user/project/import/img/gemnasium/connect_github_v13_5.png diff --git a/doc/user/project/import/img/gemnasium/create_project.png b/doc/user/project/import/img/gemnasium/create_project.png Binary files differdeleted file mode 100644 index 8edbf711629..00000000000 --- a/doc/user/project/import/img/gemnasium/create_project.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/create_project_v13_5.png b/doc/user/project/import/img/gemnasium/create_project_v13_5.png Binary files differnew file mode 100644 index 00000000000..37467bc3fed --- /dev/null +++ b/doc/user/project/import/img/gemnasium/create_project_v13_5.png diff --git a/doc/user/project/import/img/gemnasium/select_project.png b/doc/user/project/import/img/gemnasium/select_project.png Binary files differdeleted file mode 100644 index 588c5ca7ce1..00000000000 --- a/doc/user/project/import/img/gemnasium/select_project.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/select_project_v13_5.png b/doc/user/project/import/img/gemnasium/select_project_v13_5.png Binary files differnew file mode 100644 index 00000000000..30575954811 --- /dev/null +++ b/doc/user/project/import/img/gemnasium/select_project_v13_5.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index a113758495a..754c3e31799 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Migrating projects to a GitLab instance @@ -47,7 +47,7 @@ All GitLab user associations (such as comment author) will be changed to the use If you need to migrate all data over, you can leverage our [API](../../../api/README.md) to migrate from self-managed to GitLab.com. The order of assets to migrate from a self-managed instance to GitLab.com is the following: -NOTE: **Note:** +NOTE: When migrating to GitLab.com, users would need to be manually created unless [SCIM](../../../user/group/saml_sso/scim_setup.md) is going to be used. Creating users with the API is limited to self-managed instances as it requires administrator access. 1. [Groups](../../../api/groups.md) @@ -61,7 +61,7 @@ Docker pulls and pushes and re-run any CI pipelines to retrieve any build artifa ## Migrating from GitLab.com to self-managed GitLab -The process is essentially the same as for [migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). The main difference is that users can be created on the self-managed GitLab instance by an admin through the UI or the [users API](../../../api/users.md#user-creation). +The process is essentially the same as for [migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). The main difference is that users can be created on the self-managed GitLab instance by an administrator through the UI or the [users API](../../../api/users.md#user-creation). ## Migrating between two self-managed GitLab instances @@ -73,4 +73,4 @@ then restore it on the new server. In the event of merging two GitLab instances together (for example, both instances have existing data on them and one can't be wiped), refer to the instructions in [Migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). -Additionally, you can migrate users using the [Users API](../../../api/users.md) with an admin user. +Additionally, you can migrate users using the [Users API](../../../api/users.md) with an administrator user. diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 7f179865f4f..5fb737cf74a 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Import your Jira project issues to GitLab @@ -33,7 +33,7 @@ Our parser for converting text in Jira issues to GitLab Flavored Markdown is onl Jira V3 REST API. There is an [epic](https://gitlab.com/groups/gitlab-org/-/epics/2738) tracking the addition of -items, such as issue assignees, comments, and much more. These will be included in the future +items, such as issue assignees, comments, and much more. These are included in the future iterations of the GitLab Jira importer. ## Prerequisites @@ -56,7 +56,7 @@ Make sure you have the integration set up before trying to import Jira issues. To import Jira issues to a GitLab project, follow the steps below. -NOTE: **Note:** +NOTE: Importing Jira issues is done as an asynchronous background job, which may result in delays based on import queues load, system load, or other factors. Importing large projects may take several minutes depending on the size of the import. @@ -76,7 +76,7 @@ Importing large projects may take several minutes depending on the size of the i 1. Click the **Import from** dropdown and select the Jira project that you wish to import issues from. In the **Jira-GitLab user mapping template** section, the table shows to which GitLab users your Jira - users will be mapped. + users are mapped. When the form appears, the dropdown defaults to the user conducting the import. 1. To change any of the mappings, click the dropdown in the **GitLab username** column and @@ -88,6 +88,6 @@ Importing large projects may take several minutes depending on the size of the i 1. Click **Continue**. You're presented with a confirmation that import has started. While the import is running in the background, you can navigate away from the import status page - to the issues page, and you'll see the new issues appearing in the issues list. + to the issues page, and you can see the new issues appearing in the issues list. 1. To check the status of your import, go to the Jira import page again. diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index ba1e2011d08..6ef91a54987 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Import multiple repositories by uploading a manifest file diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index 4ccc34efe30..85c8a3020b9 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Migrating from Perforce Helix @@ -35,7 +35,7 @@ Git: ## Why migrate -Perforce Helix can be difficult to manage both from a user and an admin +Perforce Helix can be difficult to manage both from a user and an administrator perspective. Migrating to Git/GitLab there is: - **No licensing costs**, Git is GPL while Perforce Helix is proprietary. diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index a19068199db..189afac1226 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -2,13 +2,20 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Import Phabricator tasks into a GitLab project > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/60562) in GitLab 12.0. +WARNING: +The Phabricator task importer is in +[beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) and is +[**not** complete](https://gitlab.com/gitlab-org/gitlab/-/issues/284406). It imports +only an issue's title and description. The GitLab project created during the import +process contains only issues, and the associated repository is disabled. + GitLab allows you to import all tasks from a Phabricator instance into GitLab issues. The import creates a single project with the repository disabled. diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 5c53b6eaf06..0e8cc159aec 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Import project from repository by URL diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index d5f4a014705..3642d07106c 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Migrating from SVN to GitLab diff --git a/doc/user/project/import/tfs.md b/doc/user/project/import/tfs.md index 7b3b11b9519..31f9b200558 100644 --- a/doc/user/project/import/tfs.md +++ b/doc/user/project/import/tfs.md @@ -3,3 +3,6 @@ redirect_to: 'tfvc.md' --- This document was moved to [another location](tfvc.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/import/tfvc.md b/doc/user/project/import/tfvc.md index cbc25552873..0d347a16697 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts --- @@ -38,7 +38,7 @@ Advantages of migrating to Git/GitLab: - **No licensing costs:** Git is open source, while TFVC is proprietary. - **Shorter learning curve:** Git has a big community and a vast number of tutorials to get you started (see our [Git topic](../../../topics/git/index.md)). -- **Integration with modern tools:** After migrating to Git and GitLab, you will have +- **Integration with modern tools:** After migrating to Git and GitLab, you have an open source, end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 333c72a65b1..e3079c3731d 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -50,7 +50,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Merge Request Approvals](merge_requests/merge_request_approvals.md): Ask for approval before implementing a change **(STARTER)** - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md): - Your Git diff tool right from GitLab's UI + Your Git diff tool right from the GitLab UI - [Review Apps](../../ci/review_apps/index.md): Live preview the results of the changes proposed in a merge request in a per-branch basis - [Labels](labels.md): Organize issues and merge requests by labels @@ -69,7 +69,7 @@ When you create a project in GitLab, you'll have access to a large number of **GitLab CI/CD:** -- [GitLab CI/CD](../../ci/README.md): GitLab's built-in [Continuous Integration, Delivery, and Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) tool +- [GitLab CI/CD](../../ci/README.md): the GitLab built-in [Continuous Integration, Delivery, and Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) tool - [Container Registry](../packages/container_registry/index.md): Build and push Docker images out-of-the-box - [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy): Configure GitLab CI/CD @@ -100,7 +100,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Insights](insights/index.md): configure the Insights that matter for your projects. **(ULTIMATE)** - [Security Dashboard](../application_security/security_dashboard/index.md): Security Dashboard. **(ULTIMATE)** - [Syntax highlighting](highlighting.md): an alternative to customize - your code blocks, overriding GitLab's default choice of language. + your code blocks, overriding the GitLab default choice of language. - [Badges](badges.md): badges for the project overview. - [Releases](releases/index.md): a way to track deliverables in your project as snapshot in time of the source, build output, other metadata, and other artifacts @@ -327,7 +327,7 @@ login <gitlab_user_name> password <personal_access_token> ``` -NOTE: **Note:** +NOTE: On Windows, Go reads `~/_netrc` instead of `~/.netrc`. ### Authenticate Git fetches @@ -374,6 +374,16 @@ project `https://gitlab.com/gitlab-org/gitlab`), the repository can be cloned using the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of `git clone git@gitlab.com:gitlab-org/gitlab.git`). +## Project activity 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). + +Project details include the following analytics: + +- Deployment Frequency + +For more information, see [Project Analytics API](../../api/project_analytics.md). + ## Project APIs There are numerous [APIs](../../api/README.md) to use with your projects: @@ -394,3 +404,4 @@ There are numerous [APIs](../../api/README.md) to use with your projects: - [Traffic](../../api/project_statistics.md) - [Variables](../../api/project_level_variables.md) - [Aliases](../../api/project_aliases.md) +- [Analytics](../../api/project_analytics.md) diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index eaef0b8d69f..1efb3583fbf 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Insights **(ULTIMATE)** @@ -14,7 +14,7 @@ requests to be merged and much more.  -NOTE: **Note:** +NOTE: This feature is [also available at the group level](../../group/insights/index.md). ## View your project's Insights @@ -27,26 +27,26 @@ link in the left sidebar: ## Configure your Insights Insights are configured using a YAML file called `.gitlab/insights.yml` within -a project. That file will then be used in the project's Insights page. +a project. That file is used in the project's Insights page. See [Writing your `.gitlab/insights.yml`](#writing-your-gitlabinsightsyml) below for details about the content of this file. -NOTE: **Note:** -Once the configuration file is created, you can also +NOTE: +After the configuration file is created, you can also [use it for your project's group](../../group/insights/index.md#configure-your-insights). -NOTE: **Note:** -If the project doesn't have any configuration file, it'll try to use +NOTE: +If the project doesn't have any configuration file, it attempts to use the group configuration if possible. If the group doesn't have any -configuration, the default configuration will be used. +configuration, the default configuration is used. ## Permissions If you have access to view a project, then you have access to view their Insights. -NOTE: **Note:** +NOTE: Issues or merge requests that you don't have access to (because you don't have access to the project they belong to, or because they are confidential) are filtered out of the Insights charts. @@ -56,11 +56,11 @@ You may also consult the [group permissions table](../../permissions.md#group-me ## Writing your `.gitlab/insights.yml` The `.gitlab/insights.yml` file defines the structure and order of the Insights -charts that will be displayed in each Insights page of your project or group. +charts displayed in each Insights page of your project or group. Each page has a unique key and a collection of charts to fetch and display. -For example, here's a single definition for Insights that will display one page with one chart: +For example, here's a single definition for Insights that displays one page with one chart: ```yaml bugsCharts: @@ -103,8 +103,8 @@ The following table lists available parameters for charts: | Keyword | Description | |:---------------------------------------------------|:------------| -| [`title`](#title) | The title of the chart. This will displayed on the Insights page. | -| [`description`](#description) | A description for the individual chart. This will be displayed above the relevant chart. | +| [`title`](#title) | The title of the chart. This displays on the Insights page. | +| [`description`](#description) | A description for the individual chart. This displays above the relevant chart. | | [`type`](#type) | The type of chart: `bar`, `line` or `stacked-bar`. | | [`query`](#query) | A hash that defines the conditions for issues / merge requests to be part of the chart. | @@ -115,7 +115,7 @@ Insights charts. ### `title` -`title` is the title of the chart as it will be displayed on the Insights page. +`title` is the title of the chart as it displays on the Insights page. For example: ```yaml @@ -187,14 +187,14 @@ Defines the type of "issuable" you want to create a chart for. Supported values are: -- `issue`: The chart will display issues' data. -- `merge_request`: The chart will display merge requests' data. +- `issue`: The chart displays issues' data. +- `merge_request`: The chart displays merge requests' data. #### `query.issuable_state` Filter by the state of the queried "issuable". -By default, the `opened` state filter will be applied. +By default, the `opened` state filter is applied. Supported values are: @@ -208,7 +208,7 @@ Supported values are: Filter by labels applied to the queried "issuable". -By default, no labels filter will be applied. All the defined labels must be +By default, no labels filter is applied. All the defined labels must be applied to the "issuable" in order for it to be selected. Example: @@ -229,7 +229,7 @@ monthlyBugsCreated: Group "issuable" by the configured labels. -By default, no grouping will be done. When using this keyword, you need to +By default, no grouping is done. When using this keyword, you need to set `type` to either `line` or `stacked-bar`. Example: @@ -268,7 +268,7 @@ The unit is related to the `query.group_by` you defined. For instance if you defined `query.group_by: 'day'` then `query.period_limit: 365` would mean "Gather and display data for the last 365 days". -By default, default values will be applied depending on the `query.group_by` +By default, default values are applied depending on the `query.group_by` you defined. | `query.group_by` | Default value | @@ -293,10 +293,9 @@ The `period_field` is automatically set to: - `merged_at` if `query.issuable_state` is `merged` - `created_at` otherwise -NOTE: **Note:** -Until [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/26911), is resolved, you may see `created_at` -in place of `merged_at`. -`created_at` will be used instead. +NOTE: +Until [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/26911), is resolved, +you may see `created_at` in place of `merged_at`. `created_at` is used instead. ### `projects` @@ -304,22 +303,22 @@ in place of `merged_at`. You can limit where the "issuables" can be queried from: -- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-your-insights), with `projects`, you can limit the projects to be queried. By default, all projects under the group will be used. -- If `.gitlab/insights.yml` is used for a project's insights, specifying any other projects will yield no results. By default, the project itself will be used. +- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-your-insights), with `projects`, you can limit the projects to be queried. By default, all projects under the group are used. +- If `.gitlab/insights.yml` is used for a project's insights, specifying any other projects yields no results. By default, the project itself is used. #### `projects.only` The `projects.only` option specifies the projects which the "issuables" should be queried from. -Projects listed here will be ignored when: +Projects listed here are ignored when: - They don't exist. - The current user doesn't have sufficient permissions to read them. - They are outside of the group. In the following `insights.yml` example, we specify the projects -the queries will be used on. This example is useful when setting +the queries are used on. This example is useful when setting a group's insights: ```yaml diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 9cade323ed2..30a21dd7f66 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -1,14 +1,14 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 GitLab provides integration with Atlassian Bamboo for continuous integration. -When configured, pushes to a project will trigger a build in Bamboo automatically. -Merge requests will also display CI status showing whether the build is pending, +When configured, pushes to a project trigger a build in Bamboo automatically. +Merge requests also display CI status showing whether the build is pending, failed, or completed successfully. It also provides a link to the Bamboo build page for more information. @@ -56,12 +56,12 @@ service in GitLab. access to trigger the build plan. Leave these fields blank if you do not require authentication. 1. Save or optionally click 'Test Settings'. Please note that 'Test Settings' - will actually trigger a build in Bamboo. + actually triggers a build in Bamboo. ## Troubleshooting If builds are not triggered, ensure you entered the right GitLab IP address in Bamboo under 'Trigger IP addresses'. Also check [service hook logs](overview.md#troubleshooting-integrations) for request failures. -NOTE: **Note:** +NOTE: Starting with GitLab 8.14.0, builds are triggered on push events. diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 2ed14a4c69c..4e2ee9b3662 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -16,7 +16,7 @@ in the table below. | `issues_url` | The URL to the issue in Bugzilla project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | | `new_issue_url` | This is the URL to create a new issue in Bugzilla for the project linked to this GitLab project. Note that the `new_issue_url` requires PRODUCT_NAME to be updated with the product/project name in Bugzilla. | -Once you have configured and enabled Bugzilla you'll see the Bugzilla link on the GitLab project pages that takes you to the appropriate Bugzilla project. +Once you have configured and enabled Bugzilla, you see the Bugzilla link on the GitLab project pages that takes you to the appropriate Bugzilla project. ## Referencing issues in Bugzilla @@ -27,7 +27,7 @@ Issues in Bugzilla can be referenced in two alternative ways: then followed by capital letters, numbers or underscores, and `<ID>` is a number (example `API_32-143`). -We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker the internal issue will be linked. +We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker, the internal issue is linked. Please note that `<PROJECT>` part is ignored and links always point to the address specified in `issues_url`. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 1329f584fdc..143f0e2a25d 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -11,7 +11,7 @@ To enable the Custom Issue Tracker integration in a project: 1. Go to **Settings > Integrations**. 1. Click **Custom Issue Tracker** 1. Fill in the tracker's details, such as title, description, and URLs. - You will be able to edit these fields later as well. + You can edit these fields later as well. These are some of the required fields: @@ -19,11 +19,11 @@ To enable the Custom Issue Tracker integration in a project: | --------------- | ----------- | | **Project URL** | The URL to the project in the custom issue tracker. | | **Issues URL** | The URL to the issue in the issue tracker project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. For example, `https://customissuetracker.com/project-name/:id`. | - | **New issue URL** | Currently unused. Will be changed in a future release. | + | **New issue URL** | Currently unused. Planned to be changed in a future release. | 1. Click **Test settings and save changes**. -After you configure and enable the Custom Issue Tracker service, you'll see a link on the GitLab +After you configure and enable the Custom Issue Tracker service, you see a link on the GitLab project pages that takes you to that custom issue tracker. ## Referencing issues diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index f261362eeae..8e0a167a968 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -17,7 +17,7 @@ To send GitLab event notifications to a Discord channel, create a webhook in Dis 1. Open the Discord channel you want to receive GitLab event notifications. 1. From the channel menu, select **Edit channel**. 1. Click on **Webhooks** menu item. -1. Click the **Create Webhook** button and fill in the name of the bot that will post the messages. Optionally, edit the avatar. +1. Click the **Create Webhook** button and fill in the name of the bot to post the messages. Optionally, edit the avatar. 1. Note the URL from the **WEBHOOK URL** field. 1. Click the **Save** button. @@ -32,4 +32,4 @@ With the webhook URL created in the Discord channel, you can set up the Discord 1. Paste the webhook URL that you copied from the create Discord webhook step. 1. Configure the remaining options and click the **Save changes** button. -The Discord channel you created the webhook for will now receive notification of the GitLab events that were configured. +The Discord channel you created the webhook for now receives notification of the GitLab events that were configured. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index d8b864e0396..2274913d349 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -1,12 +1,12 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 -By enabling this service, you will receive email notifications for every change +By enabling this service, you receive email notifications for every change that is pushed to your project. From the [Integrations page](overview.md#accessing-integrations) @@ -16,8 +16,8 @@ In the _Recipients_ area, provide a list of emails separated by spaces or newlin The following options are available: -- **Push events** - Email will be triggered when a push event is received. -- **Tag push events** - Email will be triggered when a tag is created and pushed. +- **Push events** - Email is triggered when a push event is received. +- **Tag push events** - Email is triggered when a tag is created and pushed. - **Send from committer** - Send notifications from the committer's email address if the domain is part of the domain GitLab is running on (e.g. `user@gitlab.com`). - **Disable code diffs** - Don't include possibly sensitive code diffs in notification body. diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index 822483a1d5b..434ae760aff 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -1,14 +1,14 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # IBM Engineering Workflow Management (EWM) Integration **(CORE)** This service allows you to navigate from GitLab to EWM work items mentioned in merge request descriptions and commit messages. Each work item reference is automatically converted to a link back to the work item. -NOTE: **Note:** +NOTE: This IBM product was [formerly named Rational Team Concert](https://jazz.net/blog/index.php/2019/04/23/renaming-the-ibm-continuous-engineering-portfolio/)(RTC). This integration is also compatible with all versions of RTC and EWM. 1. From a GitLab project, navigate to **Settings > Integrations**, and then click **EWM**. diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md index 0e8e082859b..1fbbee36173 100644 --- a/doc/user/project/integrations/generic_alerts.md +++ b/doc/user/project/integrations/generic_alerts.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/incident_management/generic_alerts.md' --- This document was moved to [another location](../../../operations/incident_management/generic_alerts.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/integrations/github.md b/doc/user/project/integrations/github.md index 29818e862e0..5ef36ff4074 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # GitHub project integration **(PREMIUM)** @@ -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/github/authenticating-to-github/creating-a-personal-access-token) +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) with `repo:status` access granted: 1. Go to your "Personal access tokens" page at <https://github.com/settings/tokens> @@ -49,8 +49,7 @@ to configure pipelines to run for open pull requests. This makes it possible to mark these status checks as _Required_ on GitHub. With **Static status check names** enabled on the integration page, your -GitLab instance host name is going to be appended to a status check name, -whereas in case of dynamic status check names, a branch name is going to be -appended. +GitLab instance host name is appended to a status check name, +whereas in case of dynamic status check names, a branch name is appended.  diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 62fccb22d36..8344baebd82 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 Slack application **(FREE ONLY)** @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Introduced in GitLab 9.4. > - Distributed to Slack App Directory in GitLab 10.2. -NOTE: **Note:** +NOTE: The GitLab Slack application is only configurable for GitLab.com. It will **not** work for on-premises installations where you can configure the [Slack slash commands](slack_slash_commands.md) service instead. We're planning @@ -25,8 +25,7 @@ The simplest way to enable the GitLab Slack application for your workspace is to install the [GitLab application](https://slack-platform.slack.com/apps/A676ADMV5-gitlab) from the [Slack App Directory](https://slack.com/apps). -Clicking install will take you to the -[GitLab Slack application landing page](https://gitlab.com/profile/slack/edit) +Clicking install takes you to the [GitLab Slack application landing page](https://gitlab.com/profile/slack/edit) where you can select a project to enable the GitLab Slack application for.  @@ -40,7 +39,7 @@ Keep in mind that you need to have the appropriate permissions for your Slack team in order to be able to install a new application, read more in Slack's docs on [Adding an app to your workspace](https://slack.com/help/articles/202035138-Add-an-app-to-your-workspace). -To enable GitLab's service for your Slack team: +To enable the GitLab service for your Slack team: 1. Go to your project's **Settings > Integration > Slack application** (only visible on GitLab.com). @@ -71,7 +70,7 @@ GitLab error: project or alias not found After confirming the installation, you, and everyone else in your Slack team, can use all the [slash commands](../../../integration/slash_commands.md). -When you perform your first slash command you will be asked to authorize your +When you perform your first slash command, you are asked to authorize your Slack user on GitLab.com. The only difference with the [manually configurable Slack slash commands](slack_slash_commands.md) diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 54f9bd8d622..06dcca6eb44 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -14,7 +14,7 @@ The Hangouts Chat service sends notifications from GitLab to the room for which 1. Open the chat room in which you want to see the notifications. 1. From the chat room menu, select **Configure Webhooks**. -1. Click on **ADD WEBHOOK** and fill in the name of the bot that will post the messages. Optionally define avatar. +1. Click on **ADD WEBHOOK** and fill in the name of the bot to post the messages. Optionally define an avatar. 1. Click **SAVE** and copy the **Webhook URL** of your webhook. See also [the Hangouts Chat documentation for configuring incoming webhooks](https://developers.google.com/hangouts/chat/how-tos/webhooks) @@ -30,6 +30,6 @@ When you have the **Webhook URL** for your Hangouts Chat room webhook, you can s 1. Paste the **Webhook URL** that you copied from the Hangouts Chat configuration step. 1. Configure the remaining options and click `Save changes`. -Your Hangouts Chat room will now start receiving GitLab event notifications as configured. +Your Hangouts Chat room now starts receiving GitLab event notifications as configured.  diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md index 718f00273bd..7b90d8d7cfd 100644 --- a/doc/user/project/integrations/hipchat.md +++ b/doc/user/project/integrations/hipchat.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -19,7 +19,7 @@ HipChat v1 API (legacy) supports "API Auth Tokens" in the Group API menu. A v1 token is allowed to send messages to *any* room. HipChat v2 API has tokens that are can be created using the Integrations tab -in the Group or Room admin page. By design, these are lightweight tokens that +in the Group or Room administration page. By design, these are lightweight tokens that allow GitLab to send messages only to *one* room. ### Complete these steps in HipChat diff --git a/doc/user/project/integrations/img/microsoft_teams_select_incoming_webhook.png b/doc/user/project/integrations/img/microsoft_teams_select_incoming_webhook.png Binary files differnew file mode 100644 index 00000000000..216e65a8b30 --- /dev/null +++ b/doc/user/project/integrations/img/microsoft_teams_select_incoming_webhook.png diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 0a1db5da61d..0e5163e992a 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -1,13 +1,13 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 You can find the available integrations under your project's -**Settings ➔ Integrations** page. You need to have at least +**Settings > Integrations** page. You need to have at least [maintainer permission](../../permissions.md) on the project. ## Integrations @@ -16,13 +16,13 @@ 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 functionality to GitLab. -[Learn more about integrations.](overview.md) +Learn more [about integrations](overview.md). ## Project webhooks Project webhooks allow you to trigger a URL if for example new code is pushed or a new issue is created. You can configure webhooks to listen for specific events -like pushes, issues or merge requests. GitLab will send a POST request with data +like pushes, issues or merge requests. GitLab sends a POST request with data to the webhook URL. -[Learn more about webhooks.](webhooks.md) +Learn more [about webhooks](webhooks.md). diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index bb4a5b2b97f..8dd7e4309b4 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -1,20 +1,20 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 GitLab provides a way to push update messages to an Irker server. When -configured, pushes to a project will trigger the service to send data directly +configured, pushes to a project trigger the service to send data directly to the Irker server. See the project homepage for further information: <https://gitlab.com/esr/irker> ## Needed setup -You will first need an Irker daemon. You can download the Irker code +You first need an Irker daemon. You can download the Irker code [from its repository](https://gitlab.com/esr/irker): ```shell @@ -26,8 +26,8 @@ This script is the gateway script, it acts both as an IRC client, for sending messages to an IRC server obviously, and as a TCP server, for receiving messages from the GitLab service. -If the Irker server runs on the same machine, you are done. If not, you will -need to follow the firsts steps of the next section. +If the Irker server runs on the same machine, you are done. If not, you +need to follow the first steps of the next section. ## Complete these steps in GitLab @@ -40,7 +40,7 @@ need to follow the firsts steps of the next section. 1. Enter the server port of `irkerd` (e.g. defaults to 6659) in the `Server port` field on the Web page. 1. Optional: if `Default IRC URI` is set, it has to be in the format - `irc[s]://domain.name` and will be prepend to each and every channel provided + `irc[s]://domain.name` and is prepended to each and every channel provided by the user which is not a full URI. 1. Specify the recipients (e.g. #channel1, user1, etc.) 1. Save or optionally click "Test Settings". @@ -48,13 +48,13 @@ need to follow the firsts steps of the next section. ## Note on Irker recipients Irker accepts channel names of the form `chan` and `#chan`, both for the -`#chan` channel. If you want to send messages in query, you will need to add +`#chan` channel. If you want to send messages in query, you need to add `,isnick` after the channel name, in this form: `Aorimn,isnick`. In this latter case, `Aorimn` is treated as a nick and no more as a channel name. Irker can also join password-protected channels. Users need to append `?key=thesecretpassword` to the channel name. When using this feature remember to -**not** put the `#` sign in front of the channel name; failing to do so will -result on Irker joining a channel literally named `#chan?key=password` henceforth +**not** put the `#` sign in front of the channel name; failing to do so +results in Irker joining a channel literally named `#chan?key=password` henceforth leaking the channel key through the `/whois` IRC command (depending on IRC server configuration). This is due to a long standing Irker bug. diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index b4e02bbd5f3..306a16bd873 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -1,12 +1,12 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 -If you need to use Jira to track work that's implemented in GitLab, GitLab's Jira integrations make the process of working across systems more efficient. +If you need to use Jira to track work that's implemented in GitLab, Jira integrations with GitLab make the process of working across systems more efficient. This page is about the GitLab Jira integration, which is available in every GitLab project by default, allowing you to connect it to any Jira instance, whether Cloud or self-managed. To compare features with the complementary Jira Development Panel integration, see [Jira integrations](jira_integrations.md). @@ -18,7 +18,7 @@ Features include: - GitLab links to the Jira issue. - The Jira issue adds a comment with details and a link back to the activity in GitLab. - **Mention that a commit or MR resolves or closes a specific Jira issue** and when it's merged to the default branch: - - GitLab's MR displays a note that it closed the Jira issue. Prior to the merge, MRs indicate which issue they will close. + - The GitLab MR displays a note that it closed the Jira issue. Prior to the merge, MRs indicate which issue they close. - The Jira issue shows the activity and is closed or otherwise transitioned as specified in your GitLab settings. - **View a list of Jira issues directly in GitLab** **(PREMIUM)** @@ -38,7 +38,7 @@ For an overview, see [Agile Management - GitLab-Jira Basic Integration](https:// Each GitLab project can be configured to connect to an entire Jira instance. That means one GitLab project can interact with _all_ Jira projects in that instance, once -configured. Therefore, you will not have to explicitly associate +configured. Therefore, you do not have to explicitly associate a GitLab project with any single Jira project. If you have one Jira instance, you can pre-fill the settings page with a default @@ -61,7 +61,7 @@ In order to enable the Jira service in GitLab, you need to first configure the p > **Notes:** > > - The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`. -> - In order to support Oracle's Access Manager, GitLab will send additional cookies +> - In order to support Oracle's Access Manager, GitLab sends additional cookies > to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with > a value of `fromDialog`. @@ -80,17 +80,18 @@ Enter the further details on the page as described in the following table. | Field | Description | | ----- | ----------- | | `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. E.g., `https://jira.example.com`. | -| `Jira API URL` | The base URL to the Jira instance API. Web URL value will be used if not set. E.g., `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira Cloud**. | +| `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira Cloud**. | | `Username or Email` | Created in [configuring Jira](#configuring-jira) step. Use `username` for **Jira Server** or `email` for **Jira Cloud**. | | `Password/API token` |Created in [configuring Jira](#configuring-jira) step. Use `password` for **Jira Server** or `API token` for **Jira Cloud**. | -| `Transition ID` | Required for closing Jira issues via commits or merge requests. This is the ID of a transition in Jira that moves issues to a desired state. (See [Obtaining a transition ID](#obtaining-a-transition-id).) If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. | +| `Jira workflow transition IDs` | Required for closing Jira issues via commits or merge requests. These are the IDs of transitions in Jira that move issues to a particular state. (See [Obtaining a transition ID](#obtaining-a-transition-id).) If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. In GitLab 13.6 and earlier, field was called `Transition ID`. | To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and enter a Jira project key. **(PREMIUM)** You can only display issues from a single Jira project within a given GitLab project. -CAUTION: **Caution:** -If you enable Jira issues with the setting above, all users that have access to this GitLab project will be able to view all issues from the specified Jira project. +WARNING: +If you enable Jira issues with the setting above, all users that have access to this GitLab project +are able to view all issues from the specified Jira project. When you have configured all settings, click **Test settings and save changes**. @@ -127,9 +128,9 @@ Jira issue IDs must be formatted in uppercase for the integration to work. ### Reference Jira issues When GitLab project has Jira issue tracker configured and enabled, mentioning -Jira issue in GitLab will automatically add a comment in Jira issue with the +Jira issues in GitLab automatically adds a comment in Jira issue with the link back to GitLab. This means that in comments in merge requests and commits -referencing an issue, e.g., `PROJECT-7`, will add a comment in Jira issue in the +referencing an issue, `PROJECT-7` for example, adds a comment in Jira issue in the format: ```plaintext @@ -145,7 +146,7 @@ ENTITY_TITLE  -For example, the following commit will reference the Jira issue with `PROJECT-1` as its ID: +For example, the following commit references the Jira issue with `PROJECT-1` as its ID: ```shell git commit -m "PROJECT-1 Fix spelling and grammar" @@ -155,8 +156,8 @@ git commit -m "PROJECT-1 Fix spelling and grammar" Jira issues can be closed directly from GitLab by using trigger words in commits and merge requests. When a commit which contains the trigger word -followed by the Jira issue ID in the commit message is pushed, GitLab will -add a comment in the mentioned Jira issue and immediately close it (provided +followed by the Jira issue ID in the commit message is pushed, GitLab +adds a comment in the mentioned Jira issue and immediately closes it (provided the transition ID was set up correctly). There are currently three trigger words, and you can use either one to achieve @@ -168,12 +169,12 @@ the same goal: where `PROJECT-1` is the ID of the Jira issue. -> **Notes:** -> -> - Only commits and merges into the project's default branch (usually **master**) will -> close an issue in Jira. You can change your projects default branch under -> [project settings](img/jira_project_settings.png). -> - The Jira issue will not be transitioned if it has a resolution. +Note the following: + +- Only commits and merges into the project's default branch (usually `master`) + close an issue in Jira. You can change your project's default branch under + [project settings](img/jira_project_settings.png). +- The Jira issue is not transitioned if it has a resolution. Let's consider the following example: @@ -183,7 +184,7 @@ Let's consider the following example: in GitLab contains the improvement 1. In the merge request description we use the issue closing trigger `Closes PROJECT-7`. -1. Once the merge request is merged, the Jira issue will be automatically closed +1. Once the merge request is merged, the Jira issue is automatically closed with a comment and an associated link to the commit that resolved the issue. In the following screenshot you can see what the link references to the Jira @@ -191,7 +192,7 @@ issue look like.  -Once this merge request is merged, the Jira issue will be automatically closed +Once this merge request is merged, the Jira issue is automatically closed with a link to the commit that resolved the issue.  @@ -244,7 +245,7 @@ If these features do not work as expected, it is likely due to a problem with th Make sure that the Jira user you set up for the integration has the correct access permission to post comments on a Jira issue and also to transition the issue, if you'd like GitLab to also be able to do so. -Jira issue references and update comments will not work if the GitLab issue tracker is disabled. +Jira issue references and update comments do not work if the GitLab issue tracker is disabled. ### GitLab is unable to close a Jira issue @@ -259,6 +260,6 @@ Jira lists.) CAPTCHA may be triggered after several consecutive failed login attempts which may lead to a `401 unauthorized` error when testing your Jira integration. -If CAPTCHA has been triggered, you will not be able to use Jira's REST API to -authenticate with the Jira site. You will need to log in to your Jira instance +If CAPTCHA has been triggered, you can't use Jira's REST API to +authenticate with the Jira site. You need to log in to your Jira instance and complete the CAPTCHA. diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index 14999734c00..b8eebef8e42 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Creating an API token in Jira Cloud @@ -11,7 +11,7 @@ below to create one: 1. Log in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) with your email address. - NOTE: **Note:** + NOTE: It is important that the user associated with this email address has *write* access to projects in Jira. diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index dd22c26be36..f15a5ee4429 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab Issues are a tool for discussing ideas and planning and tracking work. However, your organization may already use Jira for these purposes, with extensive, established data and business processes they rely on. -Although you can [migrate](../../../user/project/import/jira.md) your Jira issues and work exclusively in GitLab, you also have the option of continuing to use Jira by using GitLab's Jira integrations. +Although you can [migrate](../../../user/project/import/jira.md) your Jira issues and work exclusively in GitLab, you also have the option of continuing to use Jira by using the GitLab Jira integrations. ## Integrations @@ -19,7 +19,7 @@ The following Jira integrations allow different types of cross-referencing betwe - [**Jira integration**](jira.md) - This is built in to GitLab. In a given GitLab project, it can be configured to connect to any Jira instance, self-managed or Cloud. - [**Jira development panel integration**](../../../integration/jira_development_panel.md) - This connects all GitLab projects under a specified group or personal namespace. - - If you're using Jira Cloud and GitLab.com, install the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-for-jira) app in the Atlassian Marketplace and see its [documentation](../../../integration/jira_development_panel.md#gitlab-for-jira-app). + - If you're using Jira Cloud and GitLab.com, install the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app in the Atlassian Marketplace and see its [documentation](../../../integration/jira_development_panel.md#gitlab-for-jira-app). - For all other environments, use the [Jira DVCS Connector configuration instructions](../../../integration/jira_development_panel.md#configuration). ### Feature comparison diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index 38098d7d15b..d2a42c0535e 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -1,18 +1,17 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Creating a username and password for Jira Server -We need to create a user in Jira which will have access to all projects that -need to integrate with GitLab. +We need to create a user in Jira to have access to all projects that need to integrate with GitLab. -As an example, we'll create a user named `gitlab` and add it to a new group +As an example, we create a user named `gitlab` and add it to a new group named `gitlab-developers`. -NOTE: **Note:** +NOTE: It is important that the Jira user created for the integration is given 'write' access to your Jira projects. This is covered in the process below. @@ -24,15 +23,16 @@ access to your Jira projects. This is covered in the process below. 1. The next step is to create a new user (e.g., `gitlab`) who has write access to projects in Jira. Enter the user's name and a _valid_ e-mail address since Jira sends a verification e-mail to set up the password. - _**Note:** Jira creates the username automatically by using the e-mail - prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You will need to create - an HTTP basic authentication password. You can do this by visiting the user - profile, looking up the username, and setting a password._ + + Jira creates the username automatically by using the e-mail + prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You + need to create an HTTP basic authentication password. You can do this by visiting the user + profile, looking up the username, and setting a password.  -1. Create a `gitlab-developers` group. (We will give this group write access to Jira - projects in a later step). Go to the **Groups** tab on the left, and select **Add group**. +1. Create a `gitlab-developers` group (we give this group write access to Jira + projects in a later step.) Go to the **Groups** tab on the left, and select **Add group**.  @@ -53,7 +53,7 @@ access to your Jira projects. This is covered in the process below. To do this, click the gear icon and select **Issues**. Then click **Permission Schemes**. Click **Add Permission Scheme** and enter a **Name** and, optionally, a **Description**. -1. Once your permission scheme is created, you'll be taken back to the permissions scheme list. +1. Once your permission scheme is created, you are taken back to the permissions scheme list. Locate your new permissions scheme and click **Permissions**. Next to **Administer Projects**, click **Edit**. In the resulting dialog box, select **Group** and select `gitlab-developers` from the dropdown. @@ -61,4 +61,4 @@ access to your Jira projects. This is covered in the process below.  The Jira configuration is complete. Write down the new Jira username and its -password as they will be needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). +password as they are needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). diff --git a/doc/user/project/integrations/kubernetes.md b/doc/user/project/integrations/kubernetes.md index ab43eb2da7e..646c9ed66d5 100644 --- a/doc/user/project/integrations/kubernetes.md +++ b/doc/user/project/integrations/kubernetes.md @@ -3,3 +3,6 @@ redirect_to: '../clusters/index.md' --- This document was moved to [another location](../clusters/index.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/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index c12a969ca3c..e80f672d05d 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -15,11 +15,11 @@ You can also use Mattermost slash commands to control GitLab inside Mattermost. To enable Mattermost integration you must create an incoming webhook integration: 1. Sign in to your Mattermost instance. -1. Visit incoming webhooks, that will be something like: `https://mattermost.example.com/your_team_name/integrations/incoming_webhooks/add`. +1. Visit incoming webhooks, that is something like: `https://mattermost.example.com/your_team_name/integrations/incoming_webhooks/add`. 1. Choose a display name, description and channel, those can be overridden on GitLab. -1. Save it, copy the **Webhook URL**, we'll need this later for GitLab. +1. Save it and copy the **Webhook URL** because we need this later for GitLab. -Incoming Webhooks might be blocked on your Mattermost instance. Ask your Mattermost admin +Incoming Webhooks might be blocked on your Mattermost instance. Ask your Mattermost administrator to enable it on: - **Mattermost System Console > Integrations > Integration Management** in Mattermost @@ -27,7 +27,7 @@ to enable it on: - **Mattermost System Console > Integrations > Custom Integrations** in Mattermost versions 5.11 and earlier. -Display name override is not enabled by default, you need to ask your admin to enable it on that same section. +Display name override is not enabled by default, you need to ask your administrator to enable it on that same section. ## On GitLab @@ -35,7 +35,7 @@ After you set up Mattermost, it's time to set up GitLab. Navigate to the [Integrations page](overview.md#accessing-integrations) and select the **Mattermost notifications** service to configure it. -There, you will see a checkbox with the following events that can be triggered: +There, you see a checkbox with the following events that can be triggered: - Push - Issue @@ -55,7 +55,7 @@ At the end, fill in your Mattermost details: | Field | Description | | ----- | ----------- | -| **Webhook** | The incoming webhook URL which you have to set up on Mattermost, it will be something like: `http://mattermost.example/hooks/5xo…` | +| **Webhook** | The incoming webhook URL which you have to set up on Mattermost, similar to: `http://mattermost.example/hooks/5xo…` | | **Username** | Optional username which can be on messages sent to Mattermost. Fill this in if you want to change the username of the bot. | | **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 5e08767d3f0..6c8a0ded2ae 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -37,13 +37,13 @@ commands in Mattermost and then enable the service in GitLab. ### Step 1. Enable custom slash commands in Mattermost -This step is only required when using a source install, Omnibus installs will be +This step is only required when using a source install. Omnibus installs 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 admin privileges and navigate to the system +1. Log in with an account that has administrator privileges and navigate to the system console.  @@ -61,13 +61,12 @@ the administrator console. 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 will appear with all the values you need to copy in Mattermost as + A screen appears with all the values you need to copy in Mattermost as described in the next step. Leave the window open. - NOTE: **Note:** - GitLab will propose some values for the Mattermost settings. The only one - required to copy-paste as-is is the **Request URL**, all the others are just - suggestions. + NOTE: + GitLab offers some values for the Mattermost settings. Only **Request URL** is required + as offered, all the others are just suggestions.  @@ -93,15 +92,15 @@ in a new 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: **Note:** + 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 will only connect a single + 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 will use it below) and +1. After you set up all the values, copy the token (we use it below) and click **Done**.  @@ -120,12 +119,12 @@ GitLab project you configured. ## Authorizing Mattermost to interact with GitLab -The first time a user will interact with the newly created slash commands, -Mattermost will trigger an authorization process. +The first time a user interacts with the newly created slash commands, +Mattermost triggers an authorization process.  -This will connect your Mattermost user with your GitLab user. You can +This connects your Mattermost user with your GitLab user. You can see all authorized chat accounts in your profile's page under **Chat**. When the authorization process is complete, you can start interacting with @@ -158,7 +157,7 @@ Mattermost webhooks do not have access to private channels. If a private channel is required, you can edit the webhook's channel in Mattermost and select a private channel. It is not possible to use different channels for -different types of notifications - all events will be sent to the specified channel. +different types of notifications. All events are sent to the specified channel. ## Further reading diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index b2a2f1c3e7b..136da05d0e8 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -9,7 +9,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## On Microsoft Teams To enable Microsoft Teams integration you must create an incoming webhook integration on Microsoft -Teams by following the steps described in [Sending messages to Connectors and Webhooks](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using). +Teams by following the steps below: + +1. Search for "incoming webhook" on the search bar in Microsoft Teams and select the + **Incoming Webhook** item. + +  + +1. Click the **Add to a team** button. +1. Select the team and channel you want to add the integration to. +1. Add a name for the webhook. The name is displayed next to every message that + comes in through the webhook. +1. Copy the webhook URL for the next steps. + +Learn more about +[setting up an incoming webhook on Microsoft Teams](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#setting-up-a-custom-incoming-webhook). ## On GitLab @@ -17,7 +31,7 @@ After you set up Microsoft Teams, it's time to set up GitLab. Navigate to the [Integrations page](overview.md#accessing-integrations) and select the **Microsoft Teams Notification** service to configure it. -There, you will see a checkbox with the following events that can be triggered: +There, you see a checkbox with the following events that can be triggered: - Push - Issue diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index 4567d345336..18f0ad6b275 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index a502dfbf320..c391877be20 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -39,7 +39,7 @@ Click on the service links to see further configuration instructions and details | [Emails on push](emails_on_push.md) | Email the commits and diff of each push to a list of recipients | No | | External Wiki | Replaces the link to the internal wiki with a link to an external wiki | No | | Flowdock | Flowdock is a collaboration web app for technical teams | No | -| [Generic alerts](../../../operations/incident_management/generic_alerts.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | +| [Generic alerts](../../../operations/incident_management/alert_integrations.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | | [GitHub](github.md) **(PREMIUM)** | Sends pipeline notifications to GitHub | No | | [Hangouts Chat](hangouts_chat.md) | Receive events notifications in Google Hangouts Chat | No | | [HipChat](hipchat.md) | Private group chat and IM | No | @@ -69,7 +69,7 @@ Click on the service links to see further configuration instructions and details > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17874) in GitLab 12.4. If a single push includes changes to more than three branches or tags, services -supported by `push_hooks` and `tag_push_hooks` events won't be executed. +supported by `push_hooks` and `tag_push_hooks` events aren't executed. The number of branches or tags supported can be changed via [`push_event_hooks_limit` application setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index 90f91fbaa0d..69e2ea2856c 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -3,3 +3,6 @@ redirect_to: 'overview.md' --- This document was moved to [Integrations](overview.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/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 97be16f8dd3..9d7960790ff 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Health -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Prometheus integration @@ -19,7 +19,7 @@ There are two ways to set up Prometheus integration, depending on where your app - For deployments on Kubernetes, GitLab can automatically [deploy and manage Prometheus](#managed-prometheus-on-kubernetes). - For other deployment targets, simply [specify the Prometheus server](#manual-configuration-of-prometheus). -Once enabled, GitLab will automatically detect metrics from known services in the [metric library](prometheus_library/index.md). You can also [add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create +Once enabled, GitLab detects metrics from known services in the [metric library](prometheus_library/index.md). You can also [add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create [custom dashboards](../../../operations/metrics/dashboards/index.md). ## Enabling Prometheus Integration @@ -48,7 +48,7 @@ Once you have a connected Kubernetes cluster, deploying a managed Prometheus is Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). -The Prometheus server will [automatically detect and monitor](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): +The Prometheus server [automatically detects and monitors](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): - `prometheus.io/scrape` to `true` to enable monitoring of the resource. - `prometheus.io/port` to define the port of the metrics endpoint. @@ -165,8 +165,8 @@ Installing and configuring Prometheus to monitor applications is fairly straight #### Configuration in GitLab -The actual configuration of Prometheus integration within GitLab is very simple. -All you will need is the domain name or IP address of the Prometheus server you'd like +The actual configuration of Prometheus integration within GitLab +requires the domain name or IP address of the Prometheus server you'd like to integrate with. If the Prometheus resource is secured with Google's Identity-Aware Proxy (IAP), additional information like Client ID and Service Account credentials can be passed which GitLab can use to access the resource. More information about authentication from a @@ -189,7 +189,7 @@ service account can be found at Google's documentation for #### Thanos configuration in GitLab You can configure [Thanos](https://thanos.io/) as a drop-in replacement for Prometheus -with GitLab. You will need the domain name or IP address of the Thanos server you'd like +with GitLab, using the domain name or IP address of the Thanos server you'd like to integrate with. 1. Navigate to the [Integrations page](overview.md#accessing-integrations). @@ -199,9 +199,10 @@ to integrate with. ### Precedence with multiple Prometheus configurations +12345678901234567890123456789012345678901234567890123456789012345678901234567890 Although you can enable both a [manual configuration](#manual-configuration-of-prometheus) -and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, only -one of them will be used: +and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, you +can use only one: - If you have enabled a [Prometheus manual configuration](#manual-configuration-of-prometheus) @@ -225,16 +226,16 @@ Developers can view the performance impact of their changes within the merge request workflow. This feature requires [Kubernetes](prometheus_library/kubernetes.md) metrics. When a source branch has been deployed to an environment, a sparkline and -numeric comparison of the average memory consumption will appear. On the +numeric comparison of the average memory consumption displays. On the sparkline, a dot indicates when the current changes were deployed, with up to 30 minutes of performance data displayed before and after. The comparison shows the difference between the 30 minute average before and after the deployment. This information is updated after each commit has been deployed. -Once merged and the target branch has been redeployed, the metrics will switch +Once merged and the target branch has been redeployed, the metrics switches to show the new environments this revision has been deployed to. -Performance data will be available for the duration it is persisted on the +Performance data is available for the duration it is persisted on the Prometheus server.  diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 70f8a55bb07..b563dd34896 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Health -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Monitoring AWS resources @@ -33,4 +33,4 @@ A sample Cloudwatch Exporter configuration file, configured for basic AWS ELB mo ## 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 will [look for an `environment` label](index.md#identifying-environments). +however, 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/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 0fbc49ddad7..c14c14658b7 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Health -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Monitoring HAProxy @@ -28,4 +28,4 @@ To get started with NGINX monitoring, you should install and configure the [HAPr ## 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 will [look for an `environment` label](index.md#identifying-environments). +however, 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/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 35b111ab2b2..501e8ba7c1d 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Health -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Prometheus Metrics library @@ -21,8 +21,8 @@ Currently supported exporters are: - [HAProxy](haproxy.md) - [Amazon Cloud Watch](cloudwatch.md) -We have tried to surface the most important metrics for each exporter, and will -be continuing to add support for additional exporters in future releases. If you +We have tried to surface the most important metrics for each exporter, and +continue to add support for additional exporters in future releases. If you would like to add support for other official exporters, contributions are welcome. ## Identifying Environments diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 43c2d305437..ae330158a58 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Health -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Monitoring Kubernetes diff --git a/doc/user/project/integrations/prometheus_library/metrics.md b/doc/user/project/integrations/prometheus_library/metrics.md index 7ace0ec5a93..a275efce5bb 100644 --- a/doc/user/project/integrations/prometheus_library/metrics.md +++ b/doc/user/project/integrations/prometheus_library/metrics.md @@ -3,3 +3,6 @@ redirect_to: 'index.md' --- This document was moved to [another location](index.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/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index 1757378fb70..4cb827b3b4a 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Health -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Monitoring NGINX @@ -29,11 +29,11 @@ NGINX server metrics are detected, which tracks the pages and content directly s ## Configuring Prometheus to monitor for NGINX metrics -To get started with NGINX monitoring, you should first enable the [VTS statistics](https://github.com/vozlt/nginx-module-vts) module for your NGINX server. This will capture and display statistics in an HTML readable form. Next, you should install and configure the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter) which parses these statistics and translates them into a Prometheus monitoring endpoint. +To get started with NGINX monitoring, you should first enable the [VTS statistics](https://github.com/vozlt/nginx-module-vts) module for your NGINX server. This captures and displays statistics in an HTML readable form. Next, you should install and configure the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter) which parses these statistics and translates them into a Prometheus monitoring endpoint. -If you are using NGINX as your Kubernetes Ingress, GitLab will [automatically detect](nginx_ingress.md) the metrics once enabled in 0.9.0 and later releases. +If you are using NGINX as your Kubernetes Ingress, GitLab [automatically detects](nginx_ingress.md) the metrics once enabled in 0.9.0 and later releases. ## 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 will [look for an `environment` label](index.md#identifying-environments). +however, 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/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index fdea800c410..f7542ec78f7 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Health -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Monitoring NGINX Ingress Controller @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the built-in Prometheus metrics included with Kubernetes NGINX Ingress controller [version 0.16.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0160) onward. -NOTE: **Note:** +NOTE: NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics exporter](nginx_ingress_vts.md), which exports metrics different than the built-in metrics. ## Requirements @@ -27,7 +27,7 @@ NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), it will [automatically be monitored](#about-managed-nginx-ingress-deployments) by Prometheus. +If you have deployed NGINX Ingress using the GitLab [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors it](#about-managed-nginx-ingress-deployments). For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: @@ -37,7 +37,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: @@ -45,11 +45,11 @@ NGINX is configured for Prometheus monitoring, by setting: - `prometheus.io/scrape: "true"`, to enable automatic discovery. - `prometheus.io/port: "10254"`, to specify the metrics port. -When used in conjunction with the GitLab deployed Prometheus service, response metrics will be automatically collected. +When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. ### Manually setting up NGINX Ingress for Prometheus monitoring -Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint will start running on port 10254. +Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint starts running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: @@ -60,6 +60,6 @@ Managing these settings depends on how NGINX Ingress has been deployed. If you h ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab will search for metrics with appropriate labels. In this case, the `ingress` label must `<CI_ENVIRONMENT_SLUG>`. +In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `ingress` label must `<CI_ENVIRONMENT_SLUG>`. -If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format will be used automatically and metrics will be detected with no action on your part. +If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index ec7b1ee6d10..c855e564753 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -1,14 +1,14 @@ --- stage: Monitor group: Health -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Monitoring NGINX Ingress Controller with VTS metrics > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13438) in GitLab 9.5. -NOTE: **Note:** +NOTE: [NGINX Ingress version 0.16](nginx_ingress.md) and above have built-in Prometheus metrics, which are different than the VTS based metrics. GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the included VTS Prometheus metrics exporter in [version 0.9.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#09-beta1) through [0.15.x](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0150). @@ -27,7 +27,7 @@ GitLab has support for automatically detecting and monitoring the Kubernetes NGI ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), it will [automatically be monitored](#about-managed-nginx-ingress-deployments) by Prometheus. +If you have deployed NGINX Ingress using the GitLab [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors](#about-managed-nginx-ingress-deployments) it. For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: @@ -37,7 +37,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: @@ -45,11 +45,11 @@ NGINX is configured for Prometheus monitoring, by setting: - `prometheus.io/scrape: "true"`, to enable automatic discovery. - `prometheus.io/port: "10254"`, to specify the metrics port. -When used in conjunction with the GitLab deployed Prometheus service, response metrics will be automatically collected. +When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. ### Manually setting up NGINX Ingress for Prometheus monitoring -Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) has built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint will start running on port 10254. +Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) has built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint begins running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: @@ -60,6 +60,6 @@ Managing these settings depends on how NGINX Ingress has been deployed. If you h ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab will search for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. +In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. -If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format will be used automatically and metrics will be detected with no action on your part. +If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. diff --git a/doc/user/project/integrations/prometheus_units.md b/doc/user/project/integrations/prometheus_units.md index ee4f3ed77d4..0c2ce3002ee 100644 --- a/doc/user/project/integrations/prometheus_units.md +++ b/doc/user/project/integrations/prometheus_units.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/metrics/dashboards/yaml_number_format.md' --- This document was moved to [another location](../../../operations/metrics/dashboards/yaml_number_format.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/integrations/redmine.md b/doc/user/project/integrations/redmine.md index 2a85dd9b79b..38d6194b390 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -15,9 +15,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w | ----- | ----------- | | `project_url` | The URL to the project in Redmine which is being linked to this GitLab project | | `issues_url` | The URL to the issue in Redmine project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | - | `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project. **This is currently not being used and will be removed in a future release.** | + | `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project. **This is currently not being used and is planned be removed in a future release.** | - Once you have configured and enabled Redmine you'll see the Redmine link on the GitLab project pages that takes you to the appropriate Redmine project. + Once you have configured and enabled Redmine, you see the Redmine link on the GitLab project pages that takes you to the appropriate Redmine project. As an example, below is a configuration for a project named `gitlab-ci`. @@ -34,7 +34,7 @@ Issues in Redmine can be referenced in two alternative ways: then followed by capital letters, numbers or underscores, and `<ID>` is a number (example `API_32-143`). -We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker the internal issue will be linked. +We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker, the internal issue is linked. Please note that `<PROJECT>` part is ignored and links always point to the address specified in `issues_url`. diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index d549921b9d9..1de69f60a34 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index abb072c9a0a..a60af93a899 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -24,8 +24,7 @@ If you disable the template: - GitLab default values again become the default values for integrations on new projects. -- Projects previously configured using the template will continue to use - those settings. +- Projects previously configured using the template continue to use those settings. If you change the template, the revised values are applied to new projects. This feature does not provide central administration of integration settings. @@ -49,7 +48,7 @@ Recommendation: - Copy the working settings from a project to the template. There is no "Test settings" option when enabling templates. If the settings do not work, -these incorrect settings will be applied to all existing projects that do not already have +these incorrect settings are applied to all existing projects that do not already have the integration configured. Fixing the integration then needs to be done project-by-project. ## Service for external issue trackers @@ -58,6 +57,6 @@ The following image shows an example service template for Redmine.  -For each project, you will still need to configure the issue tracking +For each project, you still need to configure the issue tracking URLs by replacing `:issues_tracker_id` in the above screenshot with the ID used by your external issue tracker. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index e6f12c2532f..9e9f5b8297f 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -10,16 +10,16 @@ The Slack Notifications Service allows your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up Slack notifications requires configuration changes for both Slack and GitLab. -NOTE: **Note:** +NOTE: You can also use Slack slash commands to control GitLab inside Slack. This is the separately configured [Slack slash commands](slack_slash_commands.md). ## Slack configuration 1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook). -1. Select the Slack channel where notifications will be sent to by default. +1. Select the Slack channel where notifications should be sent to by default. Click the **Add Incoming WebHooks integration** button to add the configuration. -1. Copy the **Webhook URL**, which we will use later in the GitLab configuration. +1. Copy the **Webhook URL**, which we use later in the GitLab configuration. ## GitLab configuration @@ -36,7 +36,7 @@ separately configured [Slack slash commands](slack_slash_commands.md). - To send messages to channels, enter the Slack channel names, separated by commas. - To send direct messages, use the Member ID found in the user's Slack profile. - NOTE: **Note:** + NOTE: Usernames and private channels are not supported. 1. In **Webhook**, provide the webhook URL that you copied from the @@ -47,7 +47,7 @@ separately configured [Slack slash commands](slack_slash_commands.md). to send notifications for. 1. Click **Test settings and save changes**. -Your Slack team will now start receiving GitLab event notifications as configured. +Your Slack team now starts receiving GitLab event notifications as configured. ### Triggers available for Slack notifications @@ -110,7 +110,7 @@ result = Net::HTTP.get(URI('https://<GITLAB URL>'));0 ``` If GitLab is not trusting HTTPS connections to itself, then you may -need to [add your certificate to GitLab's trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +need to [add your certificate to the GitLab trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). If GitLab is not trusting connections to Slack, then the GitLab OpenSSL trust store is incorrect. Some typical causes: overriding diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 7c2413fce81..1e4577fb88e 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 slash commands **(CORE ONLY)** @@ -14,7 +14,7 @@ Slack, without having to leave it. This requires configurations in both Slack an GitLab can also send events (e.g., `issue created`) to Slack as notifications. This is the separately configured [Slack Notifications Service](slack.md). -NOTE: **Note:** +NOTE: For GitLab.com, use the [Slack app](gitlab_slack_application.md) instead. ## Configuration diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index c4959a8711b..e8dcb577aba 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -12,7 +12,8 @@ The Unify Circuit service sends notifications from GitLab to the conversation fo 1. Open the conversation in which you want to see the notifications. 1. From the conversation menu, select **Configure Webhooks**. -1. Click **ADD WEBHOOK** and fill in the name of the bot that will post the messages. Optionally define avatar. +1. Click **ADD WEBHOOK** and fill in the name of the bot to post the messages. Optionally + define an avatar. 1. Click **SAVE** and copy the **Webhook URL** of your webhook. For more information, see the [Unify Circuit documentation for configuring incoming webhooks](https://www.circuit.com/unifyportalfaqdetail?articleId=164448). @@ -28,6 +29,6 @@ When you have the **Webhook URL** for your Unify Circuit conversation webhook, y 1. Paste the **Webhook URL** that you copied from the Unify Circuit configuration step. 1. Configure the remaining options and click `Save changes`. -Your Unify Circuit conversation will now start receiving GitLab event notifications as configured. +Your Unify Circuit conversation now starts receiving GitLab event notifications as configured.  diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 7654909b735..8a3383fd0e7 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -10,7 +10,7 @@ You can configure GitLab to send notifications to a Webex Teams space. ## Create a webhook for the space -1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/teams/applications/incoming-webhooks-cisco-systems-38054). +1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/messaging/applications/incoming-webhooks-cisco-systems-38054). 1. Click **Connect** and log in to Webex Teams, if required. 1. Enter a name for the webhook and select the space to receive the notifications. 1. Click **ADD**. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 6a436c5093e..d8b51e8b777 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1,18 +1,18 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 Project webhooks allow you to trigger a URL if for example new code is pushed or a new issue is created. You can configure webhooks to listen for specific events -like pushes, issues or merge requests. GitLab will send a POST request with data +like pushes, issues or merge requests. GitLab sends a POST request with data to the webhook URL. -In most cases, you'll need to set up your own [webhook receiver](#example-webhook-receiver) -to receive information from GitLab, and send it to another app, according to your needs. +You usually need to set up your own [webhook receiver](#example-webhook-receiver) +to receive information from GitLab and send it to another app, according to your requirements. We already have a [built-in receiver](slack.md) for sending [Slack](https://api.slack.com/incoming-webhooks) notifications _per project_. @@ -31,10 +31,9 @@ update a backup mirror, or even deploy to your production server. They are available **per project** for GitLab Community Edition, and **per project and per group** for **GitLab Enterprise Edition**. -Navigate to the webhooks page by going to your project's -**Settings ➔ Webhooks**. +Navigate to the webhooks page at your project's **Settings > Webhooks**. -NOTE: **Note:** +NOTE: On GitLab.com, the [maximum number of webhooks and their size](../../../user/gitlab_com/index.md#webhooks) per project, and per group, is limited. ## Version history @@ -55,7 +54,7 @@ Starting from GitLab 11.2: ``) have their target URL changed to an absolute URL. See [image URL rewriting](#image-url-rewriting) for more details. -## Use-cases +## Possible uses for webhooks - You can set up a webhook in GitLab to send a notification to [Slack](https://api.slack.com/incoming-webhooks) every time a job fails. @@ -65,27 +64,29 @@ Starting from GitLab 11.2: ## Webhook endpoint tips -If you are writing your own endpoint (web server) that will receive -GitLab webhooks keep in mind the following things: +If you are writing your own endpoint (web server) to receive +GitLab webhooks, keep in mind the following: -- Your endpoint should send its HTTP response as fast as possible. If - you wait too long, GitLab may decide the hook failed and retry it. +- Your endpoint should send its HTTP response as fast as possible. If the response takes longer than + the configured timeout, GitLab decides the hook failed and retries it. For information on + customizing this timeout, see + [Webhook fails or multiple webhook requests are triggered](#webhook-fails-or-multiple-webhook-requests-are-triggered). - Your endpoint should ALWAYS return a valid HTTP response. If you do - not do this then GitLab will think the hook failed and retry it. + not do this then GitLab thinks the hook failed and retries it. Most HTTP libraries take care of this for you automatically but if you are writing a low-level hook this is important to remember. - GitLab ignores the HTTP status code returned by your endpoint. ## Secret token -If you specify a secret token, it will be sent with the hook request in the +If you specify a secret token, it is sent with the hook request in the `X-Gitlab-Token` HTTP header. Your webhook endpoint can check that to verify that the request is legitimate. ## SSL verification By default, the SSL certificate of the webhook endpoint is verified based on -an internal list of Certificate Authorities, which means the certificate cannot +an internal list of Certificate Authorities. This means the certificate cannot be self-signed. You can turn this off in the webhook settings in your GitLab projects. @@ -108,15 +109,15 @@ Below are described the supported events. Triggered when you push to the repository except when pushing tags. -NOTE: **Note:** +NOTE: When more than 20 commits are pushed at once, the `commits` webhook -attribute will only contain the first 20 for performance reasons. Loading +attribute only contains the first 20 for performance reasons. Loading detailed commit data is expensive. Note that despite only 20 commits being -present in the `commits` attribute, the `total_commits_count` attribute will -contain the actual total. +present in the `commits` attribute, the `total_commits_count` attribute contains the actual total. Also, if a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) branches, this hook won't be executed. +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) +branches, this hook isn't executed. **Request header**: @@ -203,9 +204,10 @@ X-Gitlab-Event: Push Hook Triggered when you create (or delete) tags to the repository. -NOTE: **Note:** +NOTE: If a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) tags, this hook won't be executed. +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) +tags, this hook is not executed. **Request header**: @@ -407,14 +409,15 @@ X-Gitlab-Event: Issue Hook } ``` -> **Note**: `assignee` and `assignee_id` keys are deprecated and now show the first assignee only. +NOTE: +`assignee` and `assignee_id` keys are deprecated and now show the first assignee only. ### Comment events Triggered when a new comment is made on commits, merge requests, issues, and code snippets. -The note data will be stored in `object_attributes` (e.g. `note`, `noteable_type`). The -payload will also include information about the target of the comment. For example, -a comment on an issue will include the specific issue information under the `issue` key. +The note data is stored in `object_attributes` (for example, `note` or `noteable_type`). The +payload also includes information about the target of the comment. For example, +a comment on an issue includes the specific issue information under the `issue` key. Valid target types: - `commit` @@ -732,7 +735,8 @@ X-Gitlab-Event: Note Hook } ``` -> **Note**: `assignee_id` field is deprecated and now shows the first assignee only. +NOTE: +`assignee_id` field is deprecated and now shows the first assignee only. #### Comment on code snippet @@ -1358,6 +1362,38 @@ X-Gitlab-Event: Deployment Hook Note that `deployable_id` is the ID of the CI job. +### Member events + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7. + +Triggered when a user is added as a group member. + +**Request Header**: + +```plaintext +X-Gitlab-Event: Member Hook +``` + +**Request Body**: + +```json +{ + "created_at": "2020-12-11T04:57:22Z", + "updated_at": "2020-12-11T04:57:22Z", + "group_name": "webhook-test", + "group_path": "webhook-test", + "group_id": 100, + "user_username": "test_user", + "user_name": "Test User", + "user_email": "testuser@webhooktest.com", + "user_id": 64, + "group_access": "Guest", + "group_plan": null, + "expires_at": "2020-12-14T00:00:00Z", + "event_name": "user_add_to_group" +} +``` + ### Feature Flag events Triggered when a feature flag is turned on or off. @@ -1502,21 +1538,22 @@ its description:  ``` -It will appear in the webhook body as the below (assuming that GitLab is -installed at `gitlab.example.com`, and the project is at -`example-group/example-project`): +It appears in the webhook body as follows assuming that: + +- GitLab is installed at `gitlab.example.com`. +- The project is at `example-group/example-project`. ```markdown  ``` -This will not rewrite URLs that already are pointing to HTTP, HTTPS, or -protocol-relative URLs. It will also not rewrite image URLs using advanced +This doesn't rewrite URLs that already are pointing to HTTP, HTTPS, or +protocol-relative URLs. It also doesn't rewrite image URLs using advanced Markdown features, like link labels. ## Testing webhooks -You can trigger the webhook manually. Sample data from the project will be used. +You can trigger the webhook manually. Sample data from the project is used. > For example: for triggering `Push Events` your project should have at least one commit.  @@ -1528,29 +1565,36 @@ You can find records for last 2 days in "Recent Deliveries" section on the edit  -In this section you can see HTTP status code (green for 200-299 codes, red for the others, `internal error` for failed deliveries ), triggered event, a time when the event was called, elapsed time of the request. +In this section you can see: + +- HTTP status code (green for `200-299` codes, red for the others, `internal error` for failed deliveries). +- Triggered event. +- A time when the event was called. +- Elapsed time of the request. If you need more information about execution, you can click `View details` link. On this page, you can see data that GitLab sends (request headers and body) and data that it received (response headers and body). From this page, you can repeat delivery with the same data by clicking `Resend Request` button. -NOTE: **Note:** -If URL or secret token of the webhook were updated, data will be delivered to the new address. +NOTE: +If URL or secret token of the webhook were updated, data is delivered to the new address. -### Receiving duplicate or multiple webhook requests triggered by one event +### Webhook fails or multiple webhook requests are triggered -When GitLab sends a webhook it expects a response in 10 seconds (set default value). If it does not receive one, it'll retry the webhook. -If the endpoint doesn't send its HTTP response within those 10 seconds, GitLab may decide the hook failed and retry it. +When GitLab sends a webhook, it expects a response in 10 seconds by default. If it does not receive +one, it retries the webhook. If the endpoint doesn't send its HTTP response within those 10 seconds, +GitLab may decide the hook failed and retry it. -If you are receiving multiple requests, you can try increasing the default value to wait for the HTTP response after sending the webhook -by uncommenting or adding the following setting to your `/etc/gitlab/gitlab.rb`: +If your webhooks are failing or you are receiving multiple requests, you can try changing the +default value. You can do this by uncommenting or adding the following setting to your +`/etc/gitlab/gitlab.rb` file: ```ruby gitlab_rails['webhook_timeout'] = 10 ``` -### Troubleshooting: "Unable to get local issuer certificate" +### Unable to get local issuer certificate When SSL verification is enabled, this error indicates that GitLab isn't able to verify the SSL certificate of the webhook endpoint. Typically, this is because the root certificate isn't issued by a trusted certification authority as @@ -1561,7 +1605,7 @@ Missing intermediate certificates are a common point of verification failure. ## Example webhook receiver -If you want to see GitLab's webhooks in action for testing purposes you can use +If you want to see GitLab webhooks in action for testing purposes you can use a simple echo script running in a console session. For the following script to work you need to have Ruby installed. @@ -1581,7 +1625,7 @@ end server.start ``` -Pick an unused port (e.g. 8000) and start the script: `ruby print_http_body.rb +Pick an unused port (for example, `8000`) and start the script: `ruby print_http_body.rb 8000`. Then add your server as a webhook receiver in GitLab as `http://my.host:8000/`. @@ -1594,5 +1638,6 @@ example.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0 - -> / ``` -NOTE: **Note:** -You may need to [allow requests to the local network](../../../security/webhooks.md) for this receiver to be added. +NOTE: +You may need to [allow requests to the local network](../../../security/webhooks.md) for this +receiver to be added. diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index d243ffc7a37..f9b3c083a54 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -17,14 +17,14 @@ To enable YouTrack integration in a project: 1. Navigate to the project's **Settings > [Integrations](overview.md#accessing-integrations)** page. 1. Click the **YouTrack** service, ensure it's active, and enter the required details on the page as described in the table below. - | Field | Description | - |:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| - | **Project URL** | URL to the project in YouTrack which is being linked to this GitLab project. | - | **Issues URL** | URL to the issue in YouTrack project that is linked to this GitLab project. Note that the **Issues URL** requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | + | Field | Description | + |:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | **Project URL** | URL to the project in YouTrack which is being linked to this GitLab project. | + | **Issues URL** | URL to the issue in YouTrack project that is linked to this GitLab project. Note that the **Issues URL** requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | 1. Click the **Save changes** button. -Once you have configured and enabled YouTrack, you'll see the YouTrack link on the GitLab project pages that takes you to the appropriate YouTrack project. +Once you have configured and enabled YouTrack, you see the YouTrack link on the GitLab project pages that takes you to the appropriate YouTrack project. ## Disable the internal issue tracker diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 116602fbbb9..e0f66013454 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Issue Boards @@ -51,11 +51,54 @@ To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enter Watch a [video presentation](https://youtu.be/vjccjHI7aGI) of the Issue Board feature. +## Multiple issue boards + +> - [Introduced](https://about.gitlab.com/releases/2016/10/22/gitlab-8-13-released/) in GitLab 8.13. +> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. +> - Multiple issue boards per group are available in [GitLab Premium](https://about.gitlab.com/pricing/). + +Multiple issue boards allow for more than one issue board for a given project **(CORE)** or group **(PREMIUM)**. +This is great for large projects with more than one team or when a repository hosts the code of multiple products. + +Using the search box at the top of the menu, you can filter the listed boards. + +When you have ten or more boards available, a **Recent** section is also shown in the menu, with +shortcuts to your last four visited boards. + + + +When you're revisiting an issue board in a project or group with multiple boards, +GitLab automatically loads the last board you visited. + +### Create an issue board + +To create a new issue board: + +1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click **Create new board**. +1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. + +### Delete an issue board + +To delete the currently active issue board: + +1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click **Delete board**. +1. Click **Delete** to confirm. + ## Issue boards use cases 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: + +- 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> +[Cross-project Agile work management with GitLab](https://www.youtube.com/watch?v=5J0bonGoECs) (15 min, July 2020) + ### Use cases for a single issue board With the GitLab Workflow you can discuss proposals in issues, label @@ -113,7 +156,7 @@ When finished with something, they move the card to **Frontend**. The Frontend t Cards finished by the UX team automatically appear in the **Frontend** column when they are ready for them. -NOTE: **Note:** +NOTE: For a broader use case, please see the blog post [GitLab Workflow, an Overview](https://about.gitlab.com/blog/2016/10/25/gitlab-workflow-an-overview/#gitlab-workflow-use-case-scenario). For a real use case example, you can read why @@ -122,7 +165,10 @@ to improve their workflow with multiple boards. #### Quick assignments -Create lists for each of your team members and quickly drag issues onto each team member's list. +To quickly assign issues to your team members: + +1. Create [assignee lists](#assignee-lists) for each team member. +1. Drag an issue onto the team member's list. ## Issue board terminology @@ -185,41 +231,6 @@ and vice versa. GitLab issue boards are available on GitLab Core and GitLab.com Free tiers, but some advanced functionality is present in [higher tiers only](https://about.gitlab.com/pricing/). -### Multiple issue boards - -> - [Introduced](https://about.gitlab.com/releases/2016/10/22/gitlab-8-13-released/) in GitLab 8.13. -> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. -> - Multiple issue boards per group are available in [GitLab Premium](https://about.gitlab.com/pricing/). - -Multiple issue boards allow for more than one issue board for a given project or group. -This is great for large projects with more than one team or when a repository hosts the code of multiple products. - -Using the search box at the top of the menu, you can filter the listed boards. - -When you have ten or more boards available, a **Recent** section is also shown in the menu, with -shortcuts to your last four visited boards. - - - -When you're revisiting an issue board in a project or group with multiple boards, -GitLab automatically loads the last board you visited. - -#### Create an issue board - -To create a new issue board: - -1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. -1. Click **Create new board**. -1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. - -#### Delete an issue board - -To delete the currently active issue board: - -1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. -1. Click **Delete board**. -1. Click **Delete** to confirm. - ### Configurable issue boards **(STARTER)** > [Introduced](https://about.gitlab.com/releases/2017/11/22/gitlab-10-2-released/#issue-boards-configuration) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. @@ -315,6 +326,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. This feature is available both at the project and group level. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a video overview, see [Epics Swimlanes Walkthrough - 13.6](https://www.youtube.com/watch?v=nHC7-kz5P2g) (November 2020). + To group issues by epic in an issue board: 1. Select the **Group by** dropdown button. @@ -380,19 +394,6 @@ status. If you're not able to do some of the things above, make sure you have the right [permissions](#permissions). -### First time using an issue board - -> The automatic creation of the **To Do** and **Doing** lists was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202144) in GitLab 13.5. - -The first time you open an issue board, you are presented with the default lists -(**Open**, **To Do**, **Doing**, and **Closed**). - -If the **To Do** and **Doing** labels don't exist in the project or group, they are created, and -their lists appear as empty. If any of them already exists, the list is filled with the issues that -have that label. - - - ### Create a new list Create a new list by clicking the **Add list** dropdown button in the upper right corner of the issue board. @@ -419,7 +420,13 @@ To remove a list from an issue board: 1. Select **Remove list**. A confirmation dialog appears. 1. Select **OK**. -### Add issues to a list +### Add issues to a list **(CORE ONLY)** + +> - Feature flag [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47898) in GitLab 13.7. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-adding-issues-to-the-list). **(CORE ONLY)** You can add issues to a list in a project issue board by clicking the **Add issues** button in the top right corner of the issue board. This opens up a modal @@ -432,13 +439,30 @@ the list by filtering by the following: - Assignee - Author - Epic +- Iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6) - Label - Milestone - My Reaction - Release - Weight - +#### Enable or disable adding issues to the list **(CORE ONLY)** + +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 @@ -459,6 +483,7 @@ You can filter by the following: - Assignee - Author - Epic +- Iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6) - Label - Milestone - My Reaction @@ -528,6 +553,22 @@ To select and move multiple cards:  +### First time using an issue board + +> - The automatic creation of the **To Do** and **Doing** lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202144) in GitLab 13.5. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/270583) in GitLab 13.7. In GitLab 13.7 and later, the **To Do** and **Doing** columns are not automatically created. + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/270583) in GitLab 13.7. +The **To Do** and **Doing** columns are no longer automatically created. + +In GitLab 13.5 and 13.6, the first time you open an issue board, you are presented with the default lists +(**Open**, **To Do**, **Doing**, and **Closed**). + +If the **To Do** and **Doing** labels don't exist in the project or group, they are created, and +their lists appear as empty. If any of them already exists, the list is filled with the issues that +have that label. + ## Tips A few things to remember: diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index a026854a947..d81fe19c5b9 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Associate a Zoom meeting with an issue @@ -10,13 +10,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w In order to communicate synchronously for incidents management, GitLab allows to associate a Zoom meeting with an issue. -Once you start a Zoom call for a fire-fight, you need a way to -associate the conference call with an issue, so that your team -members can join swiftly without requesting a link. +After you start a Zoom call for a fire-fight, you need a way to +associate the conference call with an issue. This is so that your +team members can join swiftly without requesting a link. -## Adding a zoom meeting to an issue +## Adding a Zoom meeting to an issue -To associate a zoom meeting with an issue, you can use GitLab's +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). In an issue, leave a comment using the `/zoom` quick action followed by a valid Zoom link: @@ -26,23 +26,23 @@ In an issue, leave a comment using the `/zoom` quick action followed by a valid ``` If the Zoom meeting URL is valid and you have at least [Reporter permissions](../../permissions.md), -a system alert will notify you that the addition of the meeting URL was successful. -The issue's description will be automatically edited to include the Zoom link, and a button will -appear right under the issue's title. +a system alert notifies you of its successful addition. +The issue's description is automatically edited to include the Zoom link, and a button +appears right under the issue's title.  You are only allowed to attach a single Zoom meeting to an issue. If you attempt -to add a second Zoom meeting using the `/zoom` quick action, it won't work, you +to add a second Zoom meeting using the `/zoom` quick action, it doesn't work. You need to [remove it](#removing-an-existing-zoom-meeting-from-an-issue) first. ## Removing an existing Zoom meeting from an issue -Similarly to adding a zoom meeting, you can remove it with a quick action: +Similarly to adding a Zoom meeting, you can remove it with a quick action: ```shell /remove_zoom ``` If you have at least [Reporter permissions](../../permissions.md), -a system alert will notify you that the meeting URL was successfully removed. +a system alert notifies you that the meeting URL was successfully removed. diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md index dab79327d6a..6fa2822aa9a 100644 --- a/doc/user/project/issues/automatic_issue_closing.md +++ b/doc/user/project/issues/automatic_issue_closing.md @@ -3,3 +3,6 @@ redirect_to: 'managing_issues.md#closing-issues-automatically' --- This document was moved to [another location](managing_issues.md#closing-issues-automatically). + +<!-- 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/issues/closing_issues.md b/doc/user/project/issues/closing_issues.md index 04f1c8e1a4a..45b905f2fb5 100644 --- a/doc/user/project/issues/closing_issues.md +++ b/doc/user/project/issues/closing_issues.md @@ -3,3 +3,6 @@ redirect_to: 'managing_issues.md#closing-issues' --- This document was moved to [another location](managing_issues.md#closing-issues). + +<!-- 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/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 5bb8805159a..02cb0313a74 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Confidential issues @@ -46,7 +46,7 @@ system note in the issue's comments. ## Indications of a confidential issue -NOTE: **Note:** +NOTE: If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), you won't be able to see the confidential issues at all. @@ -100,7 +100,7 @@ confidential information prematurely. When the confidential commits are ready to be made public, this can be done by opening a merge request from the private fork to the public upstream project. -TIP: **Best practice:** +NOTE: If you create a long-lived private fork in the same group or in a sub-group of the original upstream, all the users with Developer membership to the public project will also have the same permissions in the private project. This way, diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md index 8eec29716c1..53648b53ea3 100644 --- a/doc/user/project/issues/create_new_issue.md +++ b/doc/user/project/issues/create_new_issue.md @@ -3,3 +3,6 @@ redirect_to: 'managing_issues.md#create-a-new-issue' --- This document was moved to [another location](managing_issues.md#create-a-new-issue). + +<!-- 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/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 2a75f8ad837..b5d3b71e679 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Crosslinking Issues @@ -31,7 +31,7 @@ git commit -m "this is my commit message. Related to https://gitlab.com/<usernam Of course, you can replace `gitlab.com` with the URL of your own GitLab instance. -NOTE: **Note:** +NOTE: Linking your first commit to your issue is going to be relevant for tracking your process with [GitLab Value Stream Analytics](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). It will measure the time taken for planning the implementation of that issue, diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index af9a6401474..023a8ee57bc 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Export Issues to CSV @@ -35,11 +35,11 @@ Among numerous use cases for exporting issues for CSV, we can name a few: ## Choosing which issues to include -After selecting a project, from the issues page you can narrow down which issues to export using the search bar, along with the All/Open/Closed tabs. All issues returned will be exported, including those not shown on the first page. +After selecting a project, from the issues page you can narrow down which issues to export using the search bar, along with the All/Open/Closed tabs. All issues returned are exported, including those not shown on the first page.  -You will be asked to confirm the number of issues and email address for the export, after which the email will begin being prepared. +GitLab asks you to confirm the number of issues and email address for the export, after which the email is prepared.  @@ -53,7 +53,7 @@ Exported issues are always sorted by `Issue ID`. > > **Weight** and **Locked** columns were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5300) in GitLab Starter 10.8. -Data will be encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row will be the headers, which are listed in the following table along with a description of the values: +Data wis encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row contains the headers, which are listed in the following table along with a description of the values: | Column | Description | |---------|-------------| @@ -82,4 +82,4 @@ Data will be encoded with a comma as the column delimiter, with `"` used to quot ## Limitations - Export Issues to CSV is not available at the Group's Issues List. -- As the issues will be sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 15MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately. +- As the issues are sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 15MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately. diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 2cac88b1b29..0d10f028cbf 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Importing issues from CSV @@ -11,9 +11,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w Issues can be imported to a project by uploading a CSV file with the columns `title` and `description`. -The user uploading the CSV file will be set as the author of the imported issues. +The user uploading the CSV file is set as the author of the imported issues. -NOTE: **Note:** +NOTE: A permission level of [Developer](../../permissions.md), or higher, is required to import issues. diff --git a/doc/user/project/issues/deleting_issues.md b/doc/user/project/issues/deleting_issues.md index e50259e0dcf..d8e1485a2dc 100644 --- a/doc/user/project/issues/deleting_issues.md +++ b/doc/user/project/issues/deleting_issues.md @@ -3,3 +3,6 @@ redirect_to: 'managing_issues.md#deleting-issues' --- This document was moved to [another location](managing_issues.md#deleting-issues). + +<!-- 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/issues/design_management.md b/doc/user/project/issues/design_management.md index c19c9ca0615..3739070be01 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -1,7 +1,7 @@ --- stage: Create group: Knowledge -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +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" --- # Design Management **(CORE)** @@ -37,7 +37,7 @@ to be enabled: Design Management also requires that projects are using [hashed storage](../../../administration/raketasks/storage.md#migrate-to-hashed-storage). Since - GitLab 10.0, newly created projects use hashed storage by default. A GitLab admin can verify the storage type of a + GitLab 10.0, newly created projects use hashed storage by default. A GitLab administrator can verify the storage type of a project by navigating to **Admin Area > Projects** and then selecting the project in question. A project can be identified as hashed-stored if its *Gitaly relative path* contains `@hashed`. @@ -95,7 +95,7 @@ you can drag and drop designs onto the dedicated drop zone to upload them. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202634) in GitLab 12.10, you can also copy images from your file system and -paste them directly on GitLab's Design page as a new design. +paste them directly on the GitLab Design page as a new design. On macOS you can also take a screenshot and immediately copy it to the clipboard by simultaneously clicking <kbd>Control</kbd> + <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>3</kbd>, and then paste it as a design. @@ -170,7 +170,7 @@ Once selected, click the **Delete selected** button to confirm the deletion:  -NOTE: **Note:** +NOTE: Only the latest version of the designs can be deleted. Deleted designs are not permanently lost; they can be viewed by browsing previous versions. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index b3ebefadef0..63cd784333a 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Due dates diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 716377f2e45..05e7eb3021a 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -1,10 +1,10 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- -# Issues +# Issues **(CORE)** Issues are the fundamental medium for collaborating on ideas and planning work in GitLab. @@ -35,7 +35,7 @@ you can also view all the issues collectively at the group level. See also [Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -To learn how GitLab's Strategic Marketing department uses GitLab issues with [labels](../labels.md) and +To learn how our Strategic Marketing department uses GitLab issues with [labels](../labels.md) and [issue boards](../issue_board.md), see the video on [Managing Commitments with Issues](https://www.youtube.com/watch?v=cuIHNintg1o&t=3). @@ -93,7 +93,7 @@ must be set. While you can view and manage the full details of an issue on the [issue page](#issue-page), you can also work with multiple issues at a time using the [Issues List](#issues-list), -[Issue Boards](#issue-boards), Issue references, and [Epics](#epics)**(PREMIUM)**. +[Issue Boards](#issue-boards), Issue references, and [Epics](#epics). **(PREMIUM)** Key actions for issues include: @@ -191,6 +191,7 @@ requires [GraphQL](../../../api/graphql/index.md) to be enabled. > - [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. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. To help you track the status of your issues, you can assign a status to each issue to flag work that's progressing as planned or needs attention to keep on schedule: @@ -207,16 +208,6 @@ until the issue is reopened. You can then see issue statuses in the [issue list](#issues-list) and the [Epic tree](../../group/epics/index.md#issue-health-status-in-epic-tree). -#### Disable issue health status - -This feature comes with the `:save_issuable_health_status` feature flag enabled by default. However, in some cases -this feature is incompatible with old configuration. To turn off the feature while configuration is -migrated, ask a GitLab administrator with Rails console access to run the following command: - -```ruby -Feature.disable(:save_issuable_health_status) -``` - ## Other Issue actions - [Create an issue from a template](../../project/description_templates.md#using-the-templates) diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index a5f60fbd515..2520a562f1e 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Issue Data and Actions @@ -10,14 +10,16 @@ Please read through the [GitLab Issue Documentation](index.md) for an overview o ## Parts of an Issue -The image below illustrates what an issue may look like. Note that certain parts will -look slightly different or will be absent, depending on the version of GitLab being used -and the permissions of the user viewing the issue. +The image below illustrates what an issue may look like. Certain parts +look slightly different or are absent, depending on the GitLab version +and the user's permissions. -You can find all the information for that issue on one screen. +You can find all of an issue's information on one page.  +The numbers in the image correspond to the following features: + - **1.** [Issue actions](#issue-actions) - **2.** [To Do](#to-do) - **3.** [Assignee](#assignee) @@ -47,10 +49,6 @@ You can find all the information for that issue on one screen. - **25.** [Submit comment, start a thread, or comment and close](#submit-comment-start-a-thread-or-comment-and-close) - **26.** [Zoom meetings](#zoom-meetings) -An issue starts with its status (open or closed), followed by its author, -and includes many other functionalities, numbered in the image above to -explain what they mean, one by one. - Many of the elements of the issue screen refresh automatically, such as the title and description, when they are changed by another user. Comments and system notes also update automatically in response to various actions and content updates. @@ -89,17 +87,17 @@ An issue can be assigned to: - Another person. - [Many people](#multiple-assignees). **(STARTER)** -The assignee(s) can be changed as often as needed. The idea is that the assignees are +The assignees can be changed as often as needed. The idea is that the assignees are responsible for that issue until it's reassigned to someone else to take it from there. -When assigned to someone, it will appear in their assigned issues list. +When assigned to someone, it appears in their assigned issues list. -TIP: **Tip:** +NOTE: If a user is not member of that project, it can only be assigned to them if they created the issue themselves. #### Multiple Assignees **(STARTER)** -Often multiple people work on the same issue together, which can be especially difficult +Often, multiple people work on the same issue together. This can be difficult to track in large teams where there is shared ownership of an issue. In [GitLab Starter](https://about.gitlab.com/pricing/), you can @@ -116,10 +114,10 @@ Select a [milestone](../milestones/index.md) to attribute that issue to. ### Time tracking -Use [GitLab Quick Actions](../quick_actions.md) to [track estimates and time spent on issues](../time_tracking.md). -You can add an [estimate of the time it will take](../time_tracking.md#estimates) -to resolve the issue, and also add [the time spent](../time_tracking.md#time-spent) -on the resolution of the issue. +Use [GitLab Quick Actions](../quick_actions.md) to [track estimates and time +spent on issues](../time_tracking.md). You can add a [time estimate](../time_tracking.md#estimates) +for resolving the issue, and also add [the time spent](../time_tracking.md#time-spent) +to resolve the issue. ### Due date @@ -132,13 +130,12 @@ element. Due dates can be changed as many times as needed. Categorize issues by giving them [labels](../labels.md). They help to organize workflows, and they enable you to work with the [GitLab Issue Board](index.md#issue-boards). -Group Labels, which allow you to use the same labels for all projects within the same -group, can be also given to issues. They work exactly the same, but they are immediately +Group Labels, which allow you to use the same labels for all projects in the same +group, can also be given to issues. They work exactly the same, but are immediately available to all projects in the group. -TIP: **Tip:** -If a label doesn't exist yet, you can click **Edit**, and it opens a dropdown menu -from which you can select **Create new label**. +If a label doesn't exist yet, you can create one by clicking **Edit** +followed by **Create new label** in the dropdown menu. ### Weight **(STARTER)** @@ -148,9 +145,8 @@ positive values or zero are allowed. ### Confidentiality -You can [set an issue to be confidential](confidential_issues.md). When set, unauthorized -users will not be able to access the issue, and will not see it listed in project -issue boards or the issue list. +You can [set an issue to be confidential](confidential_issues.md). Unauthorized users +cannot access the issue, and it is not listed in the project's issue boards nor list for them. ### Lock issue @@ -165,7 +161,7 @@ or were mentioned in the description or threads. ### Notifications Click on the icon to enable/disable [notifications](../../profile/notifications.md#issue--epics--merge-request-events) -for the issue. This will automatically enable if you participate in the issue in any way. +for the issue. Notifications are automatically enabled after you participate in the issue in any way. - **Enable**: If you are not a participant in the discussion on that issue, but want to receive notifications on each update, subscribe to it. @@ -180,9 +176,9 @@ for the issue. This will automatically enable if you participate in the issue in ### Edit -Clicking this icon opens the issue for editing, and you will have access to all the -same fields as when the issue was created. This icon will not display if the user -does not have permission to edit the issue. +Clicking this icon opens the issue for editing. All the fields which +were shown when the issue was created are displayed for editing. +This icon is only displayed if the user has permission to edit the issue. ### Description @@ -190,22 +186,20 @@ The plain text title and description of the issue fill the top center of the iss The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), allowing many formatting options. -> [In GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) and later, changes to an issue's description are listed in the [issue history](#issue-history).**(STARTER)** +> [In GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) and later, changes to an issue's description are listed in the [issue history](#issue-history). **(STARTER)** ### Mentions You can mention a user or a group present in your GitLab instance with `@username` or -`@groupname` and they will be notified via to-dos and email, unless they have disabled -all notifications in their profile settings. This is controlled in the -[notification settings](../../profile/notifications.md). +`@groupname`. All mentioned users are notified via to-do items and emails, +unless they have disabled all notifications in their profile settings. +This is controlled in the [notification settings](../../profile/notifications.md). -Mentions for yourself (the current logged in user), will be highlighted in a different -color, allowing you to easily see which comments involve you, helping you focus on -them quickly. +Mentions for yourself (the current logged in user) are highlighted +in a different color, which allows you to quickly see which comments involve you. -TIP: **Tip:** Avoid mentioning `@all` in issues and merge requests, as it sends an email notification -to all the members of that project's group, which can be interpreted as spam. +to all the members of that project's group. This might be interpreted as spam. ### Related Issues @@ -217,18 +211,18 @@ You can also click the `+` to add more related issues. Merge requests that were mentioned in that issue's description or in the issue thread are listed as [related merge requests](crosslinking_issues.md#from-merge-requests) here. Also, if the current issue was mentioned as related in another merge request, that -merge request will be listed here. +merge request is also listed here. ### Award emoji -You can award an emoji to that issue. There are shortcuts to "thumbs_up" and "thumbs_down", -or you can click on the light gray "face" to choose a different reaction from the -dropdown list of available [GitLab Flavored Markdown Emoji](../../markdown.md#emoji). +You can award emojis to issues. You can select the "thumbs up" and "thumbs down", +or the gray "smiley-face" to choose from the list of available +[GitLab Flavored Markdown Emoji](../../markdown.md#emoji). -TIP: **Tip:** +NOTE: Posting "+1" as a comment in a thread spams all subscribed participants of that issue, clutters the threads, and is not recommended. Awarding an emoji is a way -to let them know your reaction without spamming them. +to let them know your reaction without notifying them. ### Show all activity @@ -241,21 +235,20 @@ and selecting either: Also: - You can mention a user or a group present in your GitLab instance with - `@username` or `@groupname` and they will be notified via to-do items - and email, unless they have [disabled all notifications](#notifications) + `@username` or `@groupname` and they are notified via to-do items + and emails, unless they have [disabled all notifications](#notifications) in their profile settings. -- Mentions for yourself (the current logged in user), will be highlighted - in a different color, allowing you to easily see which comments involve you, - helping you focus on them quickly. +- Mentions for yourself (the current logged-in user) are highlighted + in a different color, which allows you to quickly see which comments involve you.  ### Create Merge Request Create a new branch and [**Draft** merge request](../merge_requests/work_in_progress_merge_requests.md) -in one action. The branch will be named `issuenumber-title` by default, but you can -choose any name, and GitLab will verify that it is not already in use. The merge request -will automatically inherit the milestone and labels of the issue, and will be set to +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 close the issue when it is merged.  @@ -288,11 +281,11 @@ supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-g ### Submit comment, start a thread, or comment and close -Once you write a comment, you can: +After you write a comment, you can: -- Click **Comment** and your comment will be published. +- Click **Comment** and to publish your comment. - Choose **Start thread** from the dropdown list and start a new [thread](../../discussions/index.md#threaded-discussions) - within that issue's main thread to discuss specific points. This invites other participants + in that issue's main thread to discuss specific points. This invites other participants to reply directly to your thread, keeping related comments grouped together.  diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index 23c1520294d..4e2c8bfd7f1 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -2,7 +2,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/issue_weight.html' stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Issue weight **(STARTER)** @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w When you have a lot of issues, it can be hard to get an overview. By adding a weight to each issue, you can get a better idea of how much time, -value or complexity a given issue has or will cost. +value or complexity a given issue has or costs. You can set the weight of an issue during its creation, by simply changing the value in the dropdown menu. You can set it to a non-negative integer @@ -20,7 +20,7 @@ upper bound is essentially limitless). You can remove weight from an issue as well. -This value will appear on the right sidebar of an individual issue, as well as +This value appears on the right sidebar of an individual issue, as well as in the issues page next to a distinctive balance scale icon. As an added bonus, you can see the total sum of all issues on the milestone page. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 62b388ec137..03060ca720c 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Managing issues @@ -99,7 +99,7 @@ When you click this link, an email address is generated and displayed, which sho by **you only**, to create issues in this project. You can save this address as a contact in your email client for easy access. -CAUTION: **Caution:** +WARNING: This is a private email address, generated just for you. **Keep it to yourself**, as anyone who knows it can create issues or merge requests as if they were you. If the address is compromised, or you'd like it to be regenerated for @@ -112,7 +112,7 @@ this project, where: - The email body becomes the issue description. - [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported. -NOTE: **Note:** +NOTE: In GitLab 11.7, we updated the format of the generated email address. However the older format is still supported, allowing existing aliases or contacts to continue working. @@ -160,7 +160,7 @@ The "Move issue" button is at the bottom of the right-sidebar when viewing the i If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script will move all the issues from one project to another that are not in status **closed**. To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below -script. Please be sure to change **project**, **admin_user** and **target_project** to your values. +script. Please be sure to change `project`, `admin_user`, and `target_project` to your values. We do also recommend [creating a backup](../../../raketasks/backup_restore.md#back-up-gitlab) before attempting any changes in the console. @@ -193,7 +193,7 @@ from its list and dropping it into the **Closed** list. ### Closing issues automatically -NOTE: **Note:** +NOTE: For performance reasons, automatic issue closing is disabled for the very first push from an existing repository. @@ -234,7 +234,7 @@ This translates to the following keywords: - Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving - Implement, Implements, Implemented, Implementing, implement, implements, implemented, implementing -Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's +Note that `%{issue_ref}` is a complex regular expression defined inside the GitLab source code that can match references to: - A local issue (`#123`). diff --git a/doc/user/project/issues/moving_issues.md b/doc/user/project/issues/moving_issues.md index 8331f865b83..3b40affcdc3 100644 --- a/doc/user/project/issues/moving_issues.md +++ b/doc/user/project/issues/moving_issues.md @@ -3,3 +3,6 @@ redirect_to: 'managing_issues.md#moving-issues' --- This document was moved to [another location](managing_issues.md#moving-issues). + +<!-- 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/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index b1806460c08..bb9038062f7 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Multiple Assignees for Issues **(STARTER)** diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index b040bcf3b03..82b2d4fde52 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Related issues **(CORE)** @@ -23,7 +23,7 @@ The relationship only shows up in the UI if the user can see both issues. When you try to close an issue that has open blockers, a warning is displayed. -TIP: **Tip:** +NOTE: To manage related issues through our API, visit the [issue links API documentation](../../../api/issue_links.md). ## Adding a related issue diff --git a/doc/user/project/issues/similar_issues.md b/doc/user/project/issues/similar_issues.md index 9cbac53ee41..79a50d5f812 100644 --- a/doc/user/project/issues/similar_issues.md +++ b/doc/user/project/issues/similar_issues.md @@ -3,3 +3,6 @@ redirect_to: 'index.md#similar-issues' --- This document was moved to [another location](index.md#similar-issues). + +<!-- 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/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 8a8359a4b02..b4cb1c383ba 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -1,13 +1,24 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- -# Sorting and ordering issue lists +# Sorting and ordering issue lists **(CORE)** -You can sort a list of issues several ways, including by issue creation date, milestone due date, -etc. The available sorting options can change based on the context of the list. +You can sort a list of issues several ways, including by: + +- Blocking +- Created date +- Due date +- Label priority +- Last updated +- Milestone due date +- Popularity +- Priority +- Weight + +The available sorting options can change based on the context of the list. For sorting by issue priority, see [Label Priority](../labels.md#label-priority). In group and project issue lists, it is also possible to order issues manually, @@ -18,19 +29,25 @@ similar to [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list). > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/62178) in GitLab 12.2. When you select **Manual** sorting, you can change -the order by dragging and dropping the issues. The changed order will persist. Everyone who visits the same list will see the reordered list, with some exceptions. +the order by dragging and dropping the issues. The changed order persists, and +everyone who visits the same list sees the updated issue order, with some exceptions. Each issue is assigned a relative order value, representing its relative -order with respect to the other issues in the list. When you drag-and-drop reorder -an issue, its relative order value changes accordingly. +order with respect to the other issues on the list. When you drag-and-drop reorder +an issue, its relative order value changes. -In addition, any time that issue appears in a manually sorted list, -the updated relative order value will be used for the ordering. This means that -if issue `A` is drag-and-drop reordered to be above issue `B` by any user in -a given list inside your GitLab instance, any time those two issues are subsequently -loaded in any list in the same instance (could be a different project issue list or a -different group issue list, for example), that ordering will be maintained. +In addition, any time an issue appears in a manually sorted list, +the updated relative order value is used for the ordering. +So, if anyone drags issue `A` above issue `B` in your GitLab instance, +this ordering is maintained whenever they appear together in any list. This ordering also affects [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list). Changing the order in an issue list changes the ordering in an issue board, and vice versa. + +## Sorting by blocking issues + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34247/) in GitLab 13.7. + +When you select to sort by **Blocking**, the issue list changes to sort descending by the +number of issues each issue is blocking. You can use this to determine the critical path for your backlog. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index c237f46b23a..2f8603e1db0 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Labels @@ -90,7 +90,7 @@ Once created, you can edit a label by clicking the pencil (**{pencil}**), or del a label by clicking the three dots (**{ellipsis_v}**) next to the **Subscribe** button and selecting **Delete**. -CAUTION: **Caution:** +WARNING: If you delete a label, it is permanently deleted. All references to the label are removed from the system and you cannot undo the deletion. #### Promote a project label to a group label @@ -109,7 +109,7 @@ with the old labels are assigned to the new group label. The new group label has the same ID as the previous project label. -CAUTION: **Caution:** +WARNING: Promoting a label is a permanent action, and cannot be reversed. To promote a project label to a group label: diff --git a/doc/user/project/maven_packages.md b/doc/user/project/maven_packages.md index 4679eed5433..5bfa08de2ed 100644 --- a/doc/user/project/maven_packages.md +++ b/doc/user/project/maven_packages.md @@ -3,3 +3,6 @@ redirect_to: '../packages/maven_repository/index.md' --- This document was moved to [another location](../packages/maven_repository/index.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/members/img/other_group_sees_shared_project.png b/doc/user/project/members/img/other_group_sees_shared_project.png Binary files differdeleted file mode 100644 index e4c93a13abb..00000000000 --- a/doc/user/project/members/img/other_group_sees_shared_project.png +++ /dev/null diff --git a/doc/user/project/members/img/other_group_sees_shared_project_v13_6.png b/doc/user/project/members/img/other_group_sees_shared_project_v13_6.png Binary files differnew file mode 100644 index 00000000000..e6e3f8f043b --- /dev/null +++ b/doc/user/project/members/img/other_group_sees_shared_project_v13_6.png diff --git a/doc/user/project/members/img/share_project_with_groups.png b/doc/user/project/members/img/share_project_with_groups.png Binary files differdeleted file mode 100644 index 0907438cb84..00000000000 --- a/doc/user/project/members/img/share_project_with_groups.png +++ /dev/null diff --git a/doc/user/project/members/img/share_project_with_groups_tab.png b/doc/user/project/members/img/share_project_with_groups_tab.png Binary files differdeleted file mode 100644 index fc489aae003..00000000000 --- a/doc/user/project/members/img/share_project_with_groups_tab.png +++ /dev/null diff --git a/doc/user/project/members/img/share_project_with_groups_tab_v13_6.png b/doc/user/project/members/img/share_project_with_groups_tab_v13_6.png Binary files differnew file mode 100644 index 00000000000..7d83659ef7a --- /dev/null +++ b/doc/user/project/members/img/share_project_with_groups_tab_v13_6.png diff --git a/doc/user/project/members/img/share_project_with_groups_v13_6.png b/doc/user/project/members/img/share_project_with_groups_v13_6.png Binary files differnew file mode 100644 index 00000000000..121e77671a3 --- /dev/null +++ b/doc/user/project/members/img/share_project_with_groups_v13_6.png diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index c66103604ed..85cb139c45b 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Members of a project @@ -53,7 +53,7 @@ that you'd like to give the user. Note that you can select more than one user.  -Once done, hit **Add users to project** and they will be immediately added to +Once done, select **Add users to project** and they are immediately added to your project with the permissions you gave them above.  @@ -71,7 +71,7 @@ In the dropdown menu, you can see only the projects you are Maintainer on.  Select the one you want and hit **Import project members**. A flash message -notifying you that the import was successful will appear, and the new members +displays, notifying you that the import was successful, and the new members are now in the project's members list. Notice that the permissions that they had on the project you imported from are retained. @@ -96,10 +96,13 @@ invitation, change their access level, or even delete them.  -Once the user accepts the invitation, they will be prompted to create a new +While unaccepted, the system automatically sends reminder emails on the second, fifth, +and tenth day after the invitation was initially sent. + +After the user accepts the invitation, they are prompted to create a new GitLab account using the same e-mail address the invitation was sent to. -Note: **Note:** +NOTE: Unaccepted invites are automatically deleted after 90 days. ## Project membership and requesting access @@ -123,7 +126,7 @@ After access is requested: Email is sent to the most recently active project maintainers. - Any project maintainer can approve or decline the request on the members page. -NOTE: **Note:** +NOTE: If a project does not have any maintainers, the notification is sent to the most recently active owners of the project's group. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 395f4353f47..edfe8ae3b5b 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Share Projects with other Groups @@ -24,35 +24,36 @@ This is where the group sharing feature can be of use. To share 'Project Acme' with the 'Engineering' group: -1. For 'Project Acme' use the left navigation menu to go to **Members** +1. For 'Project Acme' use the left navigation menu to go to **Members**. -  +  -1. Select the 'Share with group' tab -1. Add the 'Engineering' group with the maximum access level of your choice -1. Click **Share** to share it +1. Select the **Invite group** tab. +1. Add the 'Engineering' group with the maximum access level of your choice. +1. Optionally, select an expiring date. +1. Click **Invite**. -  +  -1. After sharing 'Project Acme' with 'Engineering', the project will be listed +1. After sharing 'Project Acme' with 'Engineering', the project is listed on the group dashboard -  +  Note that you can only share a project with: - groups for which you have an explicitly defined membership - groups that contain a nested subgroup or project for which you have an explicitly defined role -Admins are able to share projects with any group in the system. +Administrators are able to share projects with any group in the system. ## Maximum access level -In the example above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Maintainer' or 'Owner') will only have 'Developer' access to 'Project Acme'. +In the example above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Maintainer' or 'Owner') only have 'Developer' access to 'Project Acme'. ## Sharing public project with private group -When sharing a public project with a private group, owners and maintainers of the project will see the name of the group in the `members` page. Owners will also have the possibility to see members of the private group they don't have access to when mentioning them in the issue or merge request. +When sharing a public project with a private group, owners and maintainers of the project see the name of the group in the `members` page. Owners also have the possibility to see members of the private group they don't have access to when mentioning them in the issue or merge request. ## Share project with group lock diff --git a/doc/user/project/merge_requests.md b/doc/user/project/merge_requests.md index 1d7ebc856c3..5762177882e 100644 --- a/doc/user/project/merge_requests.md +++ b/doc/user/project/merge_requests.md @@ -3,3 +3,6 @@ redirect_to: 'merge_requests/index.md' --- This document was moved to [merge_requests/index.md](merge_requests/index.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/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index a07a155745e..c518113d3dd 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -62,14 +62,14 @@ The report for each URL is saved as an artifact that can be [viewed directly in A single `gl-accessibility.json` artifact is created and saved along with the individual HTML reports. It includes report data for all URLs scanned. -NOTE: **Note:** +NOTE: For GitLab 12.10 and earlier, the [artifact generated is named `accessibility.json`](https://gitlab.com/gitlab-org/ci-cd/accessibility/-/merge_requests/9). -NOTE: **Note:** +NOTE: For GitLab versions earlier than 12.9, you can use `include:remote` and use a link to the [current template in `master`](https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) -NOTE: **Note:** +NOTE: The job definition provided by the template does not support Kubernetes yet. It is not yet possible to pass configurations into Pa11y via CI configuration. To change anything, diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 4ba0b50a3cf..8eabef982c8 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- 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 26b3682990e..7bb64987a31 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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 040ca4b439b..04114968c80 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -44,11 +44,11 @@ between the source and target branches, and shows the information in the merge r For an example Performance job, see [Configuring Browser Performance Testing](#configuring-browser-performance-testing). -NOTE: **Note:** +NOTE: If the Browser Performance report has no data to compare, such as when you add the Browser Performance job in your `.gitlab-ci.yml` for the very first time, -the Browser Performance report widget won't show. It must have run at least -once on the target branch (`master`, for example), before it will display in a +the Browser Performance report widget doesn't show. It must have run at least +once on the target branch (`master`, for example), before it displays in a merge request targeting that branch.  @@ -72,7 +72,7 @@ using Docker-in-Docker. URL: https://example.com ``` -NOTE: **Note:** +NOTE: For versions before 12.4, see the information for [older GitLab versions](#gitlab-versions-123-and-older). If you are using a Kubernetes cluster, use [`template: Jobs/Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml) instead. @@ -81,7 +81,7 @@ The above example creates a `performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you defined in `URL` to gather key metrics. The example uses a CI/CD template that is included in all GitLab installations since -12.4, but it will not work with Kubernetes clusters. If you are using GitLab 12.3 +12.4, but it doesn't work with Kubernetes clusters. If you are using GitLab 12.3 or older, you must [add the configuration manually](#gitlab-versions-123-and-older) The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), @@ -115,7 +115,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 will only show up +This is done by setting the `DEGRADATION_THRESHOLD` variable. In the example below, the alert only shows up if the `Total Score` metric degrades by 5 points or more: ```yaml @@ -181,7 +181,7 @@ performance: ### GitLab versions 12.3 and older Browser Performance Testing has gone through several changes since it's introduction. -In this section we'll detail these changes and how you can run the test based on your +In this section we detail these changes and how you can run the test based on your 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). diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index d65c005ee34..4e87876b036 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -35,7 +35,7 @@ request thread crosslinking the new commit and the existing merge request. Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) will include cherry-picked merge commits. -NOTE: **Note:** +NOTE: We only track cherry-pick executed from GitLab (both UI and API). Support for [tracking cherry-picked commits through the command line](https://gitlab.com/gitlab-org/gitlab/-/issues/202215) is planned for a future release. ## Cherry-picking a commit diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index d50056c9450..5a98338a81b 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -45,7 +45,7 @@ Watch a quick walkthrough of Code Quality in action: <iframe src="https://www.youtube.com/embed/B32LxtJKo9M" frameborder="0" allowfullscreen="true"> </iframe> </figure> -NOTE: **Note:** +NOTE: For one customer, the auditor found that having Code Quality, SAST, and Container Scanning all automated in GitLab CI/CD was almost better than a manual review! [Read more](https://about.gitlab.com/customers/bi_worldwide/). See also the Code Climate list of [Supported Languages for Maintainability](https://docs.codeclimate.com/docs/supported-languages-for-maintainability). @@ -84,8 +84,8 @@ include: - template: Code-Quality.gitlab-ci.yml ``` -The above example will create a `code_quality` job in your CI/CD pipeline which -will scan your source code for code quality issues. The report will be saved as a +The above example creates a `code_quality` job in your CI/CD pipeline which +scans your source code for code quality issues. The report is saved as a [Code Quality report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscodequality) that you can later download and analyze. @@ -131,18 +131,18 @@ stages: - test ``` -TIP: **Tip:** -This information will be automatically extracted and shown right in the merge request widget. +NOTE: +This information is automatically extracted and shown right in the merge request widget. -CAUTION: **Caution:** +WARNING: On self-managed instances, if a malicious actor compromises the Code Quality job -definition they will be able to execute privileged Docker commands on the runner +definition they could execute privileged Docker commands on the runner host. Having proper access control policies mitigates this attack vector by allowing access only to trusted actors. ### Disabling the code quality job -The `code_quality` job will not run if the `$CODE_QUALITY_DISABLED` environment +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) to learn more about how to define one. @@ -185,7 +185,7 @@ job1: - if: '$CI_COMMIT_TAG' # Run job1 in pipelines for tags ``` -To make these work together, you will need to overwrite the code quality `rules` +To make these work together, you need to overwrite the code quality `rules` so that they match your current `rules`. From the example above, it could look like: ```yaml @@ -228,6 +228,7 @@ with the following properties: | ---------------------- | -------------------------------------------------------------------------------------- | | `description` | A description of the code quality violation. | | `fingerprint` | A unique fingerprint to identify the code quality violation. For example, an MD5 hash. | +| `severity` | A severity string (can be `info`, `minor`, `major`, `critical`, or `blocker`). | | `location.path` | The relative path to the file containing the code quality violation. | | `location.lines.begin` | The line on which the code quality violation occurred. | @@ -238,6 +239,7 @@ Example: { "description": "'unused' is assigned a value but never used.", "fingerprint": "7815696ecbf1c96e6894b779456d330e", + "severity": "minor", "location": { "path": "lib/index.js", "lines": { @@ -248,22 +250,22 @@ Example: ] ``` -NOTE: **Note:** +NOTE: Although the Code Climate spec supports more properties, those are ignored by GitLab. -## Code Quality reports **(STARTER)** +## Code Quality reports -Once the Code Quality job has completed: +After the Code Quality job completes: -- The full list of code quality violations generated by a pipeline is shown in the - Code Quality tab of the Pipeline Details page. - Potential changes to code quality are shown directly in the merge request. The Code Quality widget in the merge request compares the reports from the base and head of the branch, - then lists any violations that will be resolved or created when the branch is merged. + then lists any violations that are resolved or created when the branch is merged. - The full JSON report is available as a [downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts) for the `code_quality` job. +- The full list of code quality violations generated by a pipeline is shown in the + Code Quality tab of the Pipeline Details page. **(STARTER)** ### Generating an HTML report @@ -341,13 +343,14 @@ is still used. This can be due to multiple reasons: - You just added the Code Quality job in your `.gitlab-ci.yml`. The report does not - have anything to compare to yet, so no information can be displayed. Future merge - requests will have something to compare to. + have anything to compare to yet, so no information can be displayed. It only displays + after future merge requests have something to compare to. - Your pipeline is not set to run the code quality job on your default branch. If there is no report generated from the default branch, your MR branch reports will not have anything to compare to. - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), - nothing will be displayed. + 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. +- 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 `codeclimate.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). As a work-around, try removing [properties](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) that are [ignored by GitLab](#implementing-a-custom-tool). You can: diff --git a/doc/user/project/merge_requests/code_quality_diff.md b/doc/user/project/merge_requests/code_quality_diff.md index 0aa108a2e73..2b7b2574ef7 100644 --- a/doc/user/project/merge_requests/code_quality_diff.md +++ b/doc/user/project/merge_requests/code_quality_diff.md @@ -3,3 +3,6 @@ redirect_to: 'code_quality.md' --- This document was moved to [another location](code_quality.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/merge_requests/container_scanning.md b/doc/user/project/merge_requests/container_scanning.md index a062731ea35..5d61f2b36e8 100644 --- a/doc/user/project/merge_requests/container_scanning.md +++ b/doc/user/project/merge_requests/container_scanning.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/container_scanning/index.md' --- This document was moved to [another location](../../application_security/container_scanning/index.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/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 0495c864335..5adc4ab6b6e 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto description: "How to create Merge Requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' @@ -46,7 +46,7 @@ the merge request.  -TIP: **Tip:** +NOTE: You can push one or more times to your branch in GitLab before creating the merge request. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 52c6f8a8d41..0de9f246ceb 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Export Merge Requests to CSV **(CORE)** @@ -18,7 +18,7 @@ The following table shows what attributes will be present in the CSV. | Column | Description | |--------------------|--------------------------------------------------------------| -| MR ID | MR iid | +| MR ID | MR `iid` | | URL | A link to the merge request on GitLab | | Title | Merge request title | | State | Opened, Closed, Locked, or Merged | diff --git a/doc/user/project/merge_requests/dast.md b/doc/user/project/merge_requests/dast.md index 98a2906e560..37c0d5b4e37 100644 --- a/doc/user/project/merge_requests/dast.md +++ b/doc/user/project/merge_requests/dast.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/dast/index.md' --- This document was moved to [another location](../../application_security/dast/index.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/merge_requests/dependency_scanning.md b/doc/user/project/merge_requests/dependency_scanning.md index bdc1c355016..dd5910121ed 100644 --- a/doc/user/project/merge_requests/dependency_scanning.md +++ b/doc/user/project/merge_requests/dependency_scanning.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/dependency_scanning/index.md' --- This document was moved to [another location](../../application_security/dependency_scanning/index.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/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 60f81159394..80bdbce8d2c 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index b021fa6f336..a89acff4bfc 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 462b8f68ece..cb95daa2cab 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference description: "Getting started with Merge Requests." --- @@ -111,22 +111,23 @@ It is also possible to manage multiple assignees: - When creating a merge request. - Using [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). -## Reviewer +### Reviewer > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. -> - It's [deployed behind a feature flag](../../../user/feature_flags.md), enabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-merge-request-reviewers). **(CORE ONLY)** +> - It was [deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49787) on GitLab 13.7.1. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-merge-request-reviewers). **(CORE ONLY)** -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. Requesting a code review is an important part of contributing code. However, deciding who should review your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and reviewers makes it hard for others to determine who's doing what on a merge request. -GitLab's Merge Request Reviewers easily allow authors to request a review as well as see the status of the +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. @@ -134,23 +135,29 @@ This makes it easy to determine the relevant roles for the users involved in the To request it, open the **Reviewers** drop-down box to search for the user you wish to get a review from. -### Enable or disable Merge Request Reviewers **(CORE ONLY)** +#### Enable or disable Merge Request Reviewers **(CORE ONLY)** -Merge Request Reviewers is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. +Merge Request Reviewers is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. +can opt to disable it. To enable it: ```ruby +# For the instance Feature.enable(:merge_request_reviewers) +# For a single project +Feature.enable(:merge_request_reviewers, Project.find(<project id>)) ``` To disable it: ```ruby +# For the instance Feature.disable(:merge_request_reviewers) +# For a single project +Feature.disable(:merge_request_reviewers, Project.find(<project id>)) ``` ### Merge requests to close issues diff --git a/doc/user/project/merge_requests/img/project_merge_requests_list_view.png b/doc/user/project/merge_requests/img/project_merge_requests_list_view.png Binary files differdeleted file mode 100644 index 2c86a1ad839..00000000000 --- a/doc/user/project/merge_requests/img/project_merge_requests_list_view.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png b/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png Binary files differnew file mode 100644 index 00000000000..625d47b1142 --- /dev/null +++ b/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 69276f0677b..6af6cad5cdd 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference --- diff --git a/doc/user/project/merge_requests/license_management.md b/doc/user/project/merge_requests/license_management.md index ed81eb8ca10..4c598d851a9 100644 --- a/doc/user/project/merge_requests/license_management.md +++ b/doc/user/project/merge_requests/license_management.md @@ -3,3 +3,6 @@ redirect_to: '../../compliance/license_compliance/index.md' --- This document was moved to [another location](../../compliance/license_compliance/index.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/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 3ee88275aac..82b5d67ba2b 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -43,7 +43,7 @@ The key performance metrics that the merge request widget shows after the test c - TTFB P95: The 95th percentile for TTFB. - RPS: The average requests per second (RPS) rate the test was able to achieve. -NOTE: **Note:** +NOTE: If the Load Performance report has no data to compare, such as when you add the Load Performance job in your `.gitlab-ci.yml` for the very first time, the Load Performance report widget won't show. It must have run at least @@ -90,7 +90,7 @@ testing job in GitLab CI/CD. The easiest way to do this is to use the [`Verify/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Load-Performance-Testing.gitlab-ci.yml) template that is included with GitLab. -NOTE: **Note:** +NOTE: For large scale k6 tests you need to ensure the GitLab Runner instance performing the actual test is able to handle running the test. Refer to [k6's guidance](https://k6.io/docs/testing-guides/running-large-tests#hardware-considerations) for spec details. The [default shared GitLab.com runners](../../gitlab_com/#linux-shared-runners) @@ -119,7 +119,7 @@ An example configuration workflow: The above example creates a `load_performance` job in your CI/CD pipeline that runs the k6 test. -NOTE: **Note:** +NOTE: For Kubernetes setups a different template should be used: [`Jobs/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Load-Performance-Testing.gitlab-ci.yml). k6 has [various options](https://k6.io/docs/using-k6/options) to configure how it will run tests, such as what throughput (RPS) to run with, diff --git a/doc/user/project/merge_requests/maintainer_access.md b/doc/user/project/merge_requests/maintainer_access.md index fe7e1f558c7..29afff289fd 100644 --- a/doc/user/project/merge_requests/maintainer_access.md +++ b/doc/user/project/merge_requests/maintainer_access.md @@ -3,3 +3,6 @@ redirect_to: 'allow_collaboration.md' --- This document was moved to [another location](allow_collaboration.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/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 4b4c930c7af..01de98edeac 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, concepts --- @@ -58,7 +58,7 @@ or choose more than one. Single approval rules are available in GitLab Starter a while [multiple approval rules](#multiple-approval-rules) are available in [GitLab Premium](https://about.gitlab.com/pricing/) and above. -NOTE: **Note:** +NOTE: On GitLab.com, you can add a group as an approver if you're a member of that group or the group is public. @@ -155,7 +155,7 @@ To add or edit the default merge request approval rule: 1. Click **Add approval rule**, or **Edit**. - Add or change the **Rule name**. - - Set the number of required approvals in **No. approvals required**. The minimum value is `0`. + - Set the number of required approvals in **Approvals required**. The minimum value is `0`. - (Optional) Search for users or groups that will be [eligible to approve](#eligible-approvers) merge requests and click the **Add** button to add them as approvers. Before typing in the search field, approvers will be suggested based on the previous authors of @@ -167,7 +167,7 @@ To add or edit the default merge request approval rule: Any merge requests that were created before changing the rules will not be changed. They will keep the original approval rules, unless manually [overridden](#editing--overriding-approval-rules-per-merge-request). -NOTE: **Note:** +NOTE: If a merge request targets a different project, such as from a fork to the upstream project, the default approval rules will be taken from the target (upstream) project, not the source (fork). @@ -191,7 +191,7 @@ the same steps as [Adding / editing a default approval rule](#adding--editing-a- MR approvals can be configured to be optional. This can be useful if you're working on a team where approvals are appreciated, but not required. -To configure an approval to be optional, set the number of required approvals in **No. approvals required** to `0`. +To configure an approval to be optional, set the number of required approvals in **Approvals required** to `0`. You can also set an optional approval rule through the [Merge requests approvals API](../../../api/merge_request_approvals.md#update-merge-request-level-rule), by setting the `approvals_required` attribute to `0`. @@ -252,7 +252,7 @@ one of the following is possible:  -NOTE: **Note:** +NOTE: The merge request author is not allowed to approve their own merge request if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) is enabled in the project settings. @@ -273,7 +273,7 @@ Regardless of the approval rules you choose for your project, users can edit the request, overriding the rules you set as [default](#adding--editing-a-default-approval-rule). To prevent that from happening: -1. Uncheck the **Can override approvers and approvals required per merge request** checkbox. +1. Uncheck the **Allow overrides to approval lists per merge request (MR).** checkbox. 1. Click **Save changes**. #### Resetting approvals on push @@ -282,11 +282,11 @@ You can force all approvals on a merge request to be removed when new commits ar pushed to the source branch of the merge request. If disabled, approvals will persist even if there are changes added to the merge request. To enable this feature: -1. Check the **Remove all approvals in a merge request when new commits are pushed to its source branch** +1. Check the **Require new approvals when new commits are added to an MR.** checkbox. 1. Click **Save changes**. -NOTE: **Note:** +NOTE: Approvals do not get reset when [rebasing a merge request](fast_forward_merge.md) from the UI. However, approvals will be reset if the target branch is changed. @@ -298,7 +298,7 @@ By default, projects are configured to prevent merge requests from being approve their own authors. To change this setting: 1. Go to your project's **Settings > General**, expand **Merge request approvals**. -1. Uncheck the **Prevent approval of merge requests by merge request author** checkbox. +1. Uncheck the **Prevent MR approval by the author.** checkbox. 1. Click **Save changes**. Note that users can edit the approval rules in every merge request and override pre-defined settings unless it's set [**not to allow** overrides](#prevent-overriding-default-approvals). @@ -310,14 +310,14 @@ Note that users can edit the approval rules in every merge request and override You can prevent users that have committed to a merge request from approving it. To enable this feature: -1. Check the **Prevent approval of merge requests by their committers** checkbox. +1. Check the **Prevent MR approvals from users who make commits to the MR.** checkbox. 1. Click **Save changes**. #### Require authentication when approving a merge request > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. -NOTE: **Note:** +NOTE: To require authentication when approving a merge request, you must enable **Password authentication enabled for web interface** under [sign-in restrictions](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). in the Admin area. @@ -327,7 +327,7 @@ the approval. This enables an Electronic Signature for approvals such as the one by [CFR Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)). To enable this feature: -1. Check the **Require user password to approve** checkbox. +1. Check the **Require user password for approvals.** checkbox. 1. Click **Save changes**. ### Security approvals in merge requests **(ULTIMATE)** diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index bca9df9ae2b..4a596ed6139 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -15,7 +15,7 @@ Merge request dependencies allows a required order of merging between merge requests to be expressed. If a merge request "depends on" another, then it cannot be merged until its dependency is itself merged. -NOTE: **Note:** +NOTE: Merge requests dependencies are a **PREMIUM** feature, but this restriction is only enforced for the dependent merge request. A merge request in a **CORE** or **STARTER** project can be a dependency of a **PREMIUM** merge request, but not diff --git a/doc/user/project/merge_requests/merge_request_discussion_resolution.md b/doc/user/project/merge_requests/merge_request_discussion_resolution.md index a554d727ca4..f8d15f31875 100644 --- a/doc/user/project/merge_requests/merge_request_discussion_resolution.md +++ b/doc/user/project/merge_requests/merge_request_discussion_resolution.md @@ -3,3 +3,6 @@ redirect_to: '../../discussions/index.md' --- This document was moved to [another location](../../discussions/index.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/merge_requests/merge_when_build_succeeds.md b/doc/user/project/merge_requests/merge_when_build_succeeds.md index e37dad098f1..48d32d2882f 100644 --- a/doc/user/project/merge_requests/merge_when_build_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_build_succeeds.md @@ -5,3 +5,6 @@ redirect_to: 'merge_when_pipeline_succeeds.md' This document was moved to [merge_when_pipeline_succeeds](merge_when_pipeline_succeeds.md). >[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7135) by the "Rename MWBS service to Merge When Pipeline Succeeds" change. + +<!-- 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/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index 5151b28361a..b813e4f7d28 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -35,6 +35,11 @@ is automatically merged. When the merge request is updated with new commits, the automatic merge is canceled to allow the new changes to be reviewed. +By default, all threads must be resolved before you see the **Merge when +pipeline succeeds** button. If someone adds a new comment after +the button is selected, but before the jobs in the CI pipeline are +complete, the merge is blocked until you resolve all existing threads. + ## Only allow merge requests to be merged if the pipeline succeeds You can prevent merge requests from being merged if their pipeline did not succeed diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index b6c7ad0ce75..99e70f35d6d 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -22,7 +22,7 @@ for information on when this is available).  -NOTE: **Note:** +NOTE: GitLab resolves conflicts by creating a merge commit in the source branch that is not automatically merged into the target branch. This allows the merge commit to be reviewed and tested before the changes are merged, preventing diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 6b302b0ff02..40a4631694b 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -12,12 +12,12 @@ by clicking the **Revert** button in merge requests and commit details. ## Reverting a merge request -NOTE: **Note:** +NOTE: The **Revert** button will only be available 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: **Note:** +NOTE: The **Revert** button will only be shown 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) 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 aef68e0e771..e2d6ba9ea1c 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,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference --- @@ -18,7 +18,7 @@ View all the merge requests within a project by navigating to **Project > Merge When you access your project's merge requests, GitLab will present them in a list, and you can use the tabs available to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists). - + ## View merge requests for all projects in a group @@ -78,10 +78,7 @@ Click **Expand file** on any file to view the changes for that file. ### File-by-file diff navigation > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. -> - It's deployed behind a feature flag, enabled by default. -> - It's recommended for production use. -> - It's enabled on GitLab.com. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-by-file-diff-navigation). +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. For larger merge requests it might sometimes be useful to review single files at a time. To enable, from your avatar on the top-right navigation bar, click **Settings**, and go to **Preferences** on the left @@ -92,26 +89,16 @@ From there, when reviewing merge requests' **Changes** tab, you will see only on  -#### Enable or disable file-by-file diff navigation **(CORE ONLY)** +From [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) onwards, if you want to change +this behavior, you can do so from your **User preferences** (as explained above) or directly in a +merge request: -File-by-file diff navigation is under development but ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it for your instance. +1. Go to the merge request's **Changes** tab. +1. Click the cog icon (**{settings}**) to reveal the merge request's settings dropdown. +1. Select or deselect the checkbox **Show one file at a time** to change the setting accordingly. -To enable it: - -```ruby -# Instance-wide -Feature.enable(:view_diffs_file_by_file) -``` - -To disable it: - -```ruby -# Instance-wide -Feature.disable(:view_diffs_file_by_file>) -``` +This change overrides the choice you made in your user preferences and persists until you clear your +browser's cookies or change this behavior again. ### Merge requests commit navigation @@ -145,7 +132,7 @@ specific commit page.  -TIP: **Tip:** +NOTE: You can append `?w=1` while on the diffs page of a merge request to ignore any whitespace changes. @@ -213,7 +200,7 @@ If there's an [environment](../../../ci/environments/index.md) and the applicati successfully deployed to it, the deployed environment and the link to the Review App will be shown as well. -NOTE: **Note:** +NOTE: When the default branch (for example, `main`) is red due to a failed CI pipeline, the `merge` button When the pipeline fails in a merge request but it can be merged nonetheless, the **Merge** button will be colored in red. @@ -245,7 +232,7 @@ you can preview the changes submitted to a feature-branch through a merge reques in a per-branch basis. No need to checkout the branch, install and preview locally; all your changes will be available to preview by anyone with the Review Apps link. -With GitLab's [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the +With GitLab [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the merge request widget takes you directly to the pages changed, making it easier and faster to preview proposed modifications. @@ -296,7 +283,7 @@ Merge Request again. Here are some tips that will help you be more efficient with merge requests in the command line. -NOTE: **Note:** +NOTE: This section might move in its own document in the future. ### Copy the branch name for local checkout diff --git a/doc/user/project/merge_requests/sast.md b/doc/user/project/merge_requests/sast.md index 165290eb114..11f85749fb7 100644 --- a/doc/user/project/merge_requests/sast.md +++ b/doc/user/project/merge_requests/sast.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/sast/index.md' --- This document was moved to [another location](../../application_security/sast/index.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/merge_requests/sast_docker.md b/doc/user/project/merge_requests/sast_docker.md index a062731ea35..5d61f2b36e8 100644 --- a/doc/user/project/merge_requests/sast_docker.md +++ b/doc/user/project/merge_requests/sast_docker.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/container_scanning/index.md' --- This document was moved to [another location](../../application_security/container_scanning/index.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/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 68f5478038a..5c466654b31 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -27,7 +27,7 @@ Into a single commit on merge:  -NOTE: **Note:** +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**. @@ -36,7 +36,7 @@ The squashed commit's commit message will be 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. -NOTE: **Note:** +NOTE: This only takes effect if there are at least 2 commits. As there is nothing to squash, the commit message does not change if there is only 1 commit. It can be customized before merging a merge request. @@ -129,7 +129,7 @@ submitted to your project: 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**. -NOTE: **Note:** +NOTE: If your project is set to **Do not allow** Squash and Merge, the users still have the option to squash commits locally through the command line and force-push to their remote branch before merging. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 039f0f7d5e1..c38b28f7718 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -51,7 +51,7 @@ from any job in any stage in the pipeline. The coverage will be displayed for ea Hovering over the coverage bar will provide further information, such as the number of times the line was checked by tests. -NOTE: **Note:** +NOTE: The Cobertura XML parser currently does not support the `sources` element and ignores it. It is assumed that the `filename` of a `class` element contains the full path relative to the project root. @@ -60,7 +60,7 @@ the `filename` of a `class` element contains the full path relative to the proje ### JavaScript example The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example uses [Mocha](https://mochajs.org/) -JavaScript testing and [NYC](https://github.com/istanbuljs/nyc) coverage-tooling to +JavaScript testing and [nyc](https://github.com/istanbuljs/nyc) coverage-tooling to generate the coverage artifact: ```yaml @@ -78,7 +78,7 @@ test: #### Maven example The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java or Kotlin uses [Maven](https://maven.apache.org/) -to build the project and [Jacoco](https://www.eclemma.org/jacoco/) coverage-tooling to +to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -118,7 +118,7 @@ coverage-jdk11: #### Gradle example The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java or Kotlin uses [Gradle](https://gradle.org/) -to build the project and [Jacoco](https://www.eclemma.org/jacoco/) coverage-tooling to +to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -154,3 +154,23 @@ coverage-jdk11: reports: cobertura: build/cobertura.xml ``` + +### Python example + +The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Python uses [pytest-cov](https://pytest-cov.readthedocs.io/) to collect test coverage data and [coverage.py](https://coverage.readthedocs.io/) to convert the report to use full relative paths. +The information isn't displayed without the conversion. + +This example assumes that the code for your package is in `src/` and your tests are in `tests.py`: + +```yaml +run tests: + stage: test + image: python:3 + script: + - pip install pytest pytest-cov + - pytest --cov=src/ tests.py + - coverage xml + artifacts: + reports: + cobertura: coverage.xml +``` diff --git a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md index b298c62a5e6..9661a02a767 100644 --- a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md +++ b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index description: "Test your code and display reports in merge requests" --- diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 0922ffb2943..4ad960413ef 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -22,8 +22,8 @@ can select an older one from version dropdown.  Merge request versions are based on push not on commit. So, if you pushed 5 -commits in a single push, it will be a single option in the dropdown. If you -pushed 5 times, that will count for 5 options. +commits in a single push, it displays as a single option in the dropdown. If you +pushed 5 times, that counts for 5 options. You can also compare the merge request version with an older one to see what has changed since then. @@ -42,12 +42,12 @@ changes appears as a system note. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2383) in GitLab 10.5. -When viewing the commit details page, GitLab will link to the merge request (or +When viewing the commit details page, GitLab links to the merge request (or merge requests, if it's in more than one) containing that commit. This only applies to commits that are in the most recent version of a merge -request - if a commit was in a merge request, then rebased out of that merge -request, they will not be linked. +request - if commits were in a merge request, then rebased out of that merge +request, they aren't linked. ## `HEAD` comparison mode for Merge Requests 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 2218d38fdad..7417320eea0 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,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -14,6 +14,12 @@ being merged, and it will stay 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** will be removed in GitLab 14.0. diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index ae03be5fa0f..3e266d054be 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -2,7 +2,7 @@ type: reference stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Burndown and burnup charts **(STARTER)** @@ -66,7 +66,7 @@ and you follow this workflow: A burndown chart is available for every project or group milestone that has been attributed a **start date** and a **due date**. -NOTE: **Note:** +NOTE: You're able to [promote project](index.md#promoting-project-milestones-to-group-milestones) to group milestones and still see the **burndown chart** for them, respecting license limitations. The chart indicates the project's progress throughout that milestone (for issues assigned to it). @@ -104,13 +104,7 @@ Reopened issues are considered as having been opened on the day after they were ## Burnup charts > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. -> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-burnup-charts). **(STARTER ONLY)** - -CAUTION: **Warning:** -This feature might not be available to you. Check the **version history** note above for details. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268350) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.7. Burnup charts show the assigned and completed work for a milestone. @@ -136,25 +130,6 @@ Burnup charts can show either the total number of issues or total weight for eac day of the milestone. Use the toggle above the charts to switch between total and weight. -### Enable or disable burnup charts **(STARTER ONLY)** - -Burnup charts is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:burnup_charts) -``` - -To disable it: - -```ruby -Feature.disable(:burnup_charts) -``` - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md index 5d9e6b67bb8..2985e5da2ab 100644 --- a/doc/user/project/milestones/burndown_charts.md +++ b/doc/user/project/milestones/burndown_charts.md @@ -1,5 +1,8 @@ --- -redirect_to: './burndown_and_burnup_charts.md' +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/milestones/img/milestones_new_group_milestone.png b/doc/user/project/milestones/img/milestones_new_group_milestone.png Binary files differdeleted file mode 100644 index 5bbe8e51f23..00000000000 --- a/doc/user/project/milestones/img/milestones_new_group_milestone.png +++ /dev/null diff --git a/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png b/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png Binary files differnew file mode 100644 index 00000000000..a865221c5d7 --- /dev/null +++ b/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png diff --git a/doc/user/project/milestones/img/milestones_new_project_milestone.png b/doc/user/project/milestones/img/milestones_new_project_milestone.png Binary files differindex 2d0bdce542d..9207c9f1f7c 100644 --- a/doc/user/project/milestones/img/milestones_new_project_milestone.png +++ b/doc/user/project/milestones/img/milestones_new_project_milestone.png diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 9c47f15cb8f..acf32bb0f92 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -2,10 +2,10 @@ type: index, reference stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- -# Milestones +# Milestones **(CORE)** Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time. @@ -27,7 +27,7 @@ Similarly, milestones can be used as releases. To do so: 1. Set the milestone title to the version of your release, such as `Version 9.4`. 1. Add an issue to your release by associating the desired milestone from the issue's right-hand sidebar. -Additionally, you can integrate milestones with GitLab's [Releases feature](../releases/index.md#associate-milestones-with-a-release). +Additionally, you can integrate milestones with the [Releases feature](../releases/index.md#associate-milestones-with-a-release). ## Project milestones and group milestones @@ -46,14 +46,14 @@ For information about project and group milestones API, see: - [Project Milestones API](../../../api/milestones.md) - [Group Milestones API](../../../api/group_milestones.md) -NOTE: **Note:** -If you're in a group and click **Issues > Milestones**, you'll see group milestones and the milestones -of projects in this group. -If you're in a project and click **Issues > Milestones**, you'll only see this project's milestones. +NOTE: +If you're in a group and click **Issues > Milestones**, GitLab displays group milestones +and the milestones of projects in this group. +If you're in a project and click **Issues > Milestones**, GitLab displays only this project's milestones. ## Creating milestones -NOTE: **Note:** +NOTE: A permission level of [Developer or higher](../../permissions.md) is required to create milestones. ### New project milestone @@ -76,11 +76,11 @@ To create a **group milestone**: 1. Enter the title, an optional description, an optional start date, and an optional due date. 1. Click **New milestone**. - + ## Editing milestones -NOTE: **Note:** +NOTE: A permission level of [Developer or higher](../../permissions.md) is required to edit milestones. To edit a milestone: @@ -93,12 +93,21 @@ You can delete a milestone by clicking the **Delete** button. ### Promoting project milestones to group milestones -If you are expanding from a few projects to a larger number of projects within the same group, you may want to share the same milestone among multiple projects in the same group. If you previously created a project milestone and now want to make it available for other projects within the same group, you can promote it to a group milestone. +If you are expanding the number of projects in a group, you might want to share the same milestones +among this group's projects. You can also promote project milestones to group milestones in order to +make them available to other projects in the same group. -From the project milestone list page, you can promote a project milestone to a group milestone. This will merge all project milestones across all projects in this group with the same name into a single group milestones. All issues and merge requests that previously were assigned one of these project milestones will now be assigned the new group milestones. This action cannot be reversed and the changes are permanent. +From the project milestone list page, you can promote a project milestone to a group milestone. +This merges all project milestones across all projects in this group with the same name into a single +group milestones. All issues and merge requests that were previously assigned to one of these project +milestones is assigned the new group milestones. This action cannot be reversed and the changes are +permanent. -CAUTION: **Caution:** -From GitLab 12.4 and earlier, some information is lost when you promote a project milestone to a group milestone. Not all features on the project milestone view are available on the group milestone view. If you promote a project milestone to a group milestone, you will lose these features. See [Milestone view](#milestone-view) to see which features are missing from the group milestone view. +WARNING: +From GitLab 12.4 and earlier, some information is lost when you promote a project milestone to a +group milestone. Not all features on the project milestone view are available on the group milestone +view. If you promote a project milestone to a group milestone, you lose these features. Visit +[Milestone view](#milestone-view) to learn which features are missing from the group milestone view.  @@ -110,7 +119,7 @@ Every issue and merge request can be assigned a milestone. The milestones are vi ### Filtering in list pages -From the project issue/merge request list pages and the group issue/merge request list pages, you can [filter](../../search/index.md#issues-and-merge-requests) by both group milestones and project milestones. +From the project and group issue/merge request list pages, you can [filter](../../search/index.md#issues-and-merge-requests) by both group and project milestones. ### Filtering in issue boards @@ -125,7 +134,7 @@ When filtering by milestone, in addition to choosing a specific project mileston - **None**: Show issues or merge requests with no assigned milestone. - **Any**: Show issues or merge requests that have an assigned milestone. -- **Upcoming**: Show issues or merge requests that have been assigned the open milestone that has the next upcoming due date (i.e. nearest due date in the future). +- **Upcoming**: Show issues or merge requests that have been assigned the open milestone and has the nearest due date in the future. - **Started**: Show issues or merge requests that have an open assigned milestone with a start date that is before today. ## Milestone view @@ -148,13 +157,13 @@ There are also tabs below these that show the following: ### Project Burndown Charts **(STARTER)** -For project milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone. +For project milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, showing the progress of completing a milestone.  ### Group Burndown Charts **(STARTER)** -For group milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone. +For group milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, showing the progress of completing a milestone. ### Milestone sidebar diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index a7a72ca4d82..fd7c58f12b9 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -1,7 +1,7 @@ --- stage: Verify group: Continuous Integration -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- @@ -34,9 +34,9 @@ The reasons to do it like that are: With the new behavior, any job that is triggered by the user, is also marked with their read permissions. When a user does a `git push` or changes files through -the web UI, a new pipeline will be usually created. This pipeline will be marked +the web UI, a new pipeline is usually created. This pipeline is marked as created by the pusher (local push or via the UI) and any job created in this -pipeline will have the read permissions of the pusher but not write permissions. +pipeline has the read permissions of the pusher but not write permissions. This allows us to make it really easy to evaluate the access for all projects that have [Git submodules](../../ci/git_submodules.md) or are using container images that the pusher @@ -47,14 +47,14 @@ is running. The access is revoked after the job is finished.** It is important to note that we have a few types of users: -- **Administrators**: CI jobs created by Administrators will not have access +- **Administrators**: CI jobs created by Administrators don't have access to all GitLab projects, but only to projects and container images of projects that the administrator is a member of. That means that if a project is either public or internal users have access anyway, but if a project is private, the - Administrator will have to be a member of it in order to have access to it + Administrator has to be a member of it in order to have access to it via another project's job. -- **External users**: CI jobs created by [external users](../permissions.md#external-users) will have +- **External users**: CI jobs created by [external users](../permissions.md#external-users) have access only to projects to which the user has at least Reporter access. This rules out accessing all internal projects by default. @@ -75,7 +75,9 @@ Let's consider the following scenario: A unique job token is generated for each job and provides the user read access all projects that would be normally accessible to the user creating that job. The unique job token does not have any write permissions, but there -is a [proposal to add support](https://gitlab.com/gitlab-org/gitlab/-/issues/35067). +is a [proposal to add support](https://gitlab.com/groups/gitlab-org/-/epics/3559). + +If you need your CI pipeline to push to the Package Registry, consider using [deploy tokens](deploy_tokens/index.md). We try to make sure that this token doesn't leak by: @@ -149,8 +151,8 @@ the container registry. ### Prerequisites to use the new permissions model -With the new permissions model in place, there may be times that your job will -fail. This is most likely because your project tries to access other project's +With the new permissions model in place, there may be times that your job +fails. This is most likely because your project tries to access other project's sources, and you don't have the appropriate permissions. In the job log look for information about 403 or forbidden access messages. @@ -158,7 +160,7 @@ In short here's what you need to do should you encounter any issues. As an administrator: -- **500 errors**: You will need to update [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) to at +- **500 errors**: You need to update [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) to at least 0.8.2. This is done automatically for Omnibus installations, you need to [check manually](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/update) for installations from source. - **500 errors**: Check if you have another web proxy sitting in front of NGINX (HAProxy, @@ -185,7 +187,7 @@ git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/<user>/<mydependent ``` It can also be used for system-wide authentication -(only do this in a Docker container, it will overwrite ~/.netrc): +(only do this in a Docker container, it overwrites `~/.netrc`): ```shell echo -e "machine gitlab.com\nlogin gitlab-ci-token\npassword ${CI_JOB_TOKEN}" > ~/.netrc @@ -201,18 +203,17 @@ To properly configure submodules with GitLab CI/CD, read the With the update permission model we also extended the support for accessing Container Registries for private projects. -> **Notes:** -> -> - GitLab Runner versions prior to 1.8 don't incorporate the introduced changes -> for permissions. This makes the `image:` directive not work with private -> projects automatically and it needs to be configured manually on the GitLab Runner host -> with a predefined account (for example administrator's personal account with -> access token created explicitly for this purpose). This issue is resolved with -> latest changes in GitLab Runner 1.8 which receives GitLab credentials with -> build data. -> - Starting from GitLab 8.12, if you have [2FA](../profile/account/two_factor_authentication.md) enabled in your account, you need -> to pass a [personal access token](../profile/personal_access_tokens.md) instead of your password in order to -> login to GitLab's Container Registry. +GitLab Runner versions prior to 1.8 don't incorporate the introduced changes +for permissions. This makes the `image:` directive not work with private +projects automatically and it needs to be configured manually on the GitLab Runner host +with a predefined account (for example administrator's personal account with +access token created explicitly for this purpose). This issue is resolved with +latest changes in GitLab Runner 1.8 which receives GitLab credentials with +build data. + +Starting from GitLab 8.12, if you have [2FA](../profile/account/two_factor_authentication.md) enabled in your account, you need +to pass a [personal access token](../profile/personal_access_tokens.md) instead of your password in order to +login to the Container Registry. Your jobs can access all container images that you would normally have access to. The only implication is that you can push to the Container Registry of the diff --git a/doc/user/project/operations/alert_management.md b/doc/user/project/operations/alert_management.md index 0feed7dbf40..e60e7d93d12 100644 --- a/doc/user/project/operations/alert_management.md +++ b/doc/user/project/operations/alert_management.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/incident_management/index.md' --- This document was moved to [another location](../../../operations/incident_management/index.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/operations/dashboard_settings.md b/doc/user/project/operations/dashboard_settings.md index 2640f2cf98f..ef106181acc 100644 --- a/doc/user/project/operations/dashboard_settings.md +++ b/doc/user/project/operations/dashboard_settings.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/metrics/dashboards/settings.md' --- This document was moved to [another location](../../../operations/metrics/dashboards/settings.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/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md index 3c00c4a6c41..399ab0d53dc 100644 --- a/doc/user/project/operations/error_tracking.md +++ b/doc/user/project/operations/error_tracking.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/error_tracking.md' --- This document was moved to [another location](../../../operations/error_tracking.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/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md index b0f7cfc966a..03f2cad6d78 100644 --- a/doc/user/project/operations/feature_flags.md +++ b/doc/user/project/operations/feature_flags.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/feature_flags.md' --- This document was moved to [another location](../../../operations/feature_flags.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/operations/index.md b/doc/user/project/operations/index.md index 9cec578bc5e..d19cf393883 100644 --- a/doc/user/project/operations/index.md +++ b/doc/user/project/operations/index.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/index.md' --- This document was moved to [another location](../../../operations/index.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/operations/linking_to_an_external_dashboard.md b/doc/user/project/operations/linking_to_an_external_dashboard.md index 2640f2cf98f..ef106181acc 100644 --- a/doc/user/project/operations/linking_to_an_external_dashboard.md +++ b/doc/user/project/operations/linking_to_an_external_dashboard.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/metrics/dashboards/settings.md' --- This document was moved to [another location](../../../operations/metrics/dashboards/settings.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/operations/tracing.md b/doc/user/project/operations/tracing.md index 87567f45560..dcf9894f9e1 100644 --- a/doc/user/project/operations/tracing.md +++ b/doc/user/project/operations/tracing.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/tracing.md' --- This document was moved to [another location](../../../operations/tracing.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/packages/maven.md b/doc/user/project/packages/maven.md index 8378b8c78cd..13b5d69586a 100644 --- a/doc/user/project/packages/maven.md +++ b/doc/user/project/packages/maven.md @@ -3,3 +3,6 @@ redirect_to: '../../packages/maven_repository/index.md' --- This document was moved to [another location](../../packages/maven_repository/index.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/packages/maven_packages.md b/doc/user/project/packages/maven_packages.md index 8378b8c78cd..13b5d69586a 100644 --- a/doc/user/project/packages/maven_packages.md +++ b/doc/user/project/packages/maven_packages.md @@ -3,3 +3,6 @@ redirect_to: '../../packages/maven_repository/index.md' --- This document was moved to [another location](../../packages/maven_repository/index.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/packages/maven_repository.md b/doc/user/project/packages/maven_repository.md index 8378b8c78cd..13b5d69586a 100644 --- a/doc/user/project/packages/maven_repository.md +++ b/doc/user/project/packages/maven_repository.md @@ -3,3 +3,6 @@ redirect_to: '../../packages/maven_repository/index.md' --- This document was moved to [another location](../../packages/maven_repository/index.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/packages/npm_registry.md b/doc/user/project/packages/npm_registry.md index e94599cf33a..f874b05e7e2 100644 --- a/doc/user/project/packages/npm_registry.md +++ b/doc/user/project/packages/npm_registry.md @@ -3,3 +3,6 @@ redirect_to: '../../packages/npm_registry/index.md' --- This document was moved to [another location](../../packages/npm_registry/index.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/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 810538ab460..4aa89ec6f8d 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -1,8 +1,8 @@ --- type: concepts stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 --- # DNS records overview @@ -23,7 +23,7 @@ GitLab Pages site. Note that **how to** add DNS records depends on which server your domain is hosted on. Every control panel has its own place to do it. If you are -not an admin of your domain, and don't have access to your registrar, +not an administrator of your domain, and don't have access to your registrar, you'll need to ask for the technical support of your hosting service to do it for you. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index 9b43dd58afe..f8173b4c004 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -1,8 +1,8 @@ --- disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html' stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 domains and SSL/TLS Certificates @@ -84,7 +84,7 @@ server running on your instance).  -CAUTION: **Caution:** +WARNING: Note that if you use your root domain for your GitLab Pages website **only**, and if your domain registrar supports this feature, you can add a DNS apex `CNAME` record instead of an `A` record. The main @@ -157,7 +157,7 @@ Once you have added all the DNS records: As soon as your domain becomes active, your website will be available through your domain name. -CAUTION: **Caution:** +WARNING: Considering GitLab instances with domain verification enabled, if the domain cannot be verified for 7 days, it will be removed from the GitLab project. @@ -167,7 +167,7 @@ from the GitLab project. > - Domain verification is **required for GitLab.com users**; for GitLab self-managed instances, your GitLab administrator has the option to [disabled custom domain verification](../../../../administration/pages/index.md#custom-domain-verification). -> - [DNS propagation may take some time (up to 24h)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes/), +> - [DNS propagation may take some time (up to 24h)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/complete-guide-to-dns-records/), although it's usually a matter of minutes to complete. Until it does, verification will fail and attempts to visit your domain will respond with a 404. > - Once your domain has been verified, leave the verification record @@ -190,6 +190,22 @@ Expect the output: _gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN>. 300 IN TXT "gitlab-pages-verification-code=<YOUR-VERIFICATION-CODE>" ``` +In some cases it can help to add the verification code with the same domain name as you are trying to register. + +For a root domain: + +| From | DNS Record | To | +| ------------------------------------------------- | ---------- | ---------------------- | +| `example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | + +For a subdomain: + +| From | DNS Record | To | +| ------------------------------------------------- | ---------- | ---------------------- | +| `www.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.www.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | + ### Adding more domain aliases You can add more than one alias (custom domains and subdomains) to the same project. @@ -280,7 +296,7 @@ To make your website's visitors even more secure, you can choose to force HTTPS for GitLab Pages. By doing so, all attempts to visit your website via HTTP will be automatically redirected to HTTPS via 301. -It works with both GitLab's default domain and with your custom +It works with both the GitLab default domain and with your custom domain (as long as you've set a valid certificate for it). To enable this setting: diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 24b202dfdbd..3dea35153e4 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -2,8 +2,8 @@ type: reference description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 Pages integration with Let's Encrypt @@ -18,7 +18,7 @@ GitLab does it for you, out-of-the-box. [Let's Encrypt](https://letsencrypt.org) is a free, automated, and open source Certificate Authority. -CAUTION: **Caution:** +WARNING: This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(CORE ONLY)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3342). ## Requirements @@ -33,7 +33,7 @@ Before you can enable automatic provisioning of an SSL certificate for your doma and verified your ownership. - Verified your website is up and running, accessible through your custom domain. -GitLab's Let's Encrypt integration is enabled and available on GitLab.com. +The GitLab integration with Let's Encrypt is enabled and available on GitLab.com. For **self-managed** GitLab instances, make sure your administrator has [enabled it](../../../../administration/pages/index.md#lets-encrypt-integration). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index f30361e6669..dc73a664324 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -1,8 +1,8 @@ --- type: concepts stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 --- # SSL/TLS Certificates @@ -16,8 +16,8 @@ up your Pages project with your custom (sub)domain, if you want it secured by HTTPS, you will have to issue a certificate for that (sub)domain and install it on your project. -NOTE: **Note:** -Certificates are NOT required to add to your custom +NOTE: +Certificates are **not** required to add to your custom (sub)domain on your GitLab Pages project, though they are highly recommendable. @@ -56,7 +56,7 @@ reiterating the importance of HTTPS. ## Issuing Certificates -GitLab Pages accepts certificates provided in the [PEM](https://knowledge.digicert.com/quovadis) format, issued by +GitLab Pages accepts certificates provided in the [PEM](https://knowledge.digicert.com/quovadis.html) format, issued by [Certificate Authorities](https://en.wikipedia.org/wiki/Certificate_authority) or as [self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). Note that [self-signed certificates are typically not used](https://www.mcafee.com/blogs/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/) for public websites for security reasons and to ensure that browsers trust your site's certificate. diff --git a/doc/user/project/pages/getting_started/fork_sample_project.md b/doc/user/project/pages/getting_started/fork_sample_project.md index 250e90f0302..2cf118c9066 100644 --- a/doc/user/project/pages/getting_started/fork_sample_project.md +++ b/doc/user/project/pages/getting_started/fork_sample_project.md @@ -3,3 +3,6 @@ redirect_to: 'pages_forked_sample_project.md' --- This document was moved to [pages_forked_sample_project.md](pages_forked_sample_project.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/new_or_existing_website.md b/doc/user/project/pages/getting_started/new_or_existing_website.md index f19334a1764..2fc833fbd34 100644 --- a/doc/user/project/pages/getting_started/new_or_existing_website.md +++ b/doc/user/project/pages/getting_started/new_or_existing_website.md @@ -3,3 +3,6 @@ redirect_to: 'pages_ci_cd_template.md' --- This document was moved to [another location](pages_ci_cd_template.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_bundled_template.md b/doc/user/project/pages/getting_started/pages_bundled_template.md index bc706105606..0dab1f6ee19 100644 --- a/doc/user/project/pages/getting_started/pages_bundled_template.md +++ b/doc/user/project/pages/getting_started/pages_bundled_template.md @@ -3,3 +3,6 @@ redirect_to: 'pages_new_project_template.md' --- This document was moved to [pages_new_project_template.md](pages_new_project_template.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 906ffe43285..6dd431e02b0 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 @@ -1,8 +1,8 @@ --- type: reference, howto stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 a Pages website by using a CI/CD template diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index 7dc3d2197b5..525bbde4671 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -1,13 +1,13 @@ --- type: reference, howto stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 a Pages website from a forked sample -GitLab provides [sample projects for the most popular Static Site Generators](https://gitlab.com/pages). +GitLab provides [sample projects for the most popular Static Site Generators (SSG)](https://gitlab.com/pages). You can fork one of the sample projects and run the CI/CD pipeline to generate a Pages website. Fork a sample project when you want to test GitLab Pages or start a new project that's already 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 e030326ac5f..230e88f35f5 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -1,7 +1,7 @@ --- stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 a GitLab Pages website from scratch diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index cfa4e0910db..eec8349abe6 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -1,8 +1,8 @@ --- type: reference, howto stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 a Pages website from a new project template diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md index e45befe004e..361323a9073 100644 --- a/doc/user/project/pages/getting_started_part_four.md +++ b/doc/user/project/pages/getting_started_part_four.md @@ -3,3 +3,6 @@ redirect_to: 'getting_started/pages_from_scratch.md' --- This document was moved to [getting_started/pages_from_scratch.md](getting_started/pages_from_scratch.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_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 5ef0c4cc7b9..f549c4e6e7d 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,7 +1,7 @@ --- stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 Pages domain names, URLs, and baseurls @@ -33,7 +33,7 @@ Pages domains are `*.gitlab.io`. | Project pages owned by a group | `projectname` | `http(s)://groupname.example.io/projectname`| | Project pages owned by a subgroup | `subgroup/projectname` | `http(s)://groupname.example.io/subgroup/projectname`| -CAUTION: **Warning:** +WARNING: There are some known [limitations](introduction.md#limitations) regarding namespaces served under the general domain name and HTTPS. Make sure to read that section. @@ -80,6 +80,9 @@ To understand Pages domains clearly, read the examples below. ## URLs and baseurls +NOTE: +The `baseurl` option might be called named differently in some static site generators. + Every Static Site Generator (SSG) default configuration expects to find your website under a (sub)domain (`example.com`), not in a subdirectory of that domain (`example.com/subdir`). Therefore, @@ -96,7 +99,7 @@ baseurl: "/blog" ``` On the contrary, if you deploy your website after forking one of -our [default examples](https://gitlab.com/pages), the baseurl will +our [default examples](https://gitlab.com/pages), the `baseurl` will already be configured this way, as all examples there are project websites. If you decide to make yours a user or group website, you'll have to remove this configuration from your project. For the Jekyll @@ -106,6 +109,9 @@ example we've just mentioned, you'd have to change Jekyll's `_config.yml` to: baseurl: "" ``` +If you're using the [plain HTML example](https://gitlab.com/pages/plain-html), +you don't need to set a `baseurl`. + ## Custom domains GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS. diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 4bf5300aa13..9d7f401ca91 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -3,3 +3,6 @@ redirect_to: 'custom_domains_ssl_tls_certification/index.md' --- This document was moved to [another location](custom_domains_ssl_tls_certification/index.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_part_two.md b/doc/user/project/pages/getting_started_part_two.md index 70e84f5d486..4b2b186ca28 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -3,3 +3,6 @@ redirect_to: 'index.md' --- This document was moved to [another location](index.md#getting-started). + +<!-- 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/index.md b/doc/user/project/pages/index.md index f5cd6991869..846d30e898c 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -1,8 +1,8 @@ --- description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.' stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 Pages @@ -83,9 +83,9 @@ to build your site and publish it to the GitLab Pages server. The sequence of scripts that GitLab CI/CD runs to accomplish this task is created from a file named `.gitlab-ci.yml`, which you can [create and modify](getting_started/pages_from_scratch.md) at will. A specific `job` called `pages` in the configuration file will make GitLab aware that you are deploying a GitLab Pages website. -You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-default-domain-names), +You can either use the GitLab [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-default-domain-names), `*.gitlab.io`, or your own domain (`example.com`). In that case, you'll -need admin access to your domain's registrar (or control panel) to set it up with Pages. +need administrator access to your domain's registrar (or control panel) to set it up with Pages. The following diagrams show the workflows you might follow to get started with Pages. @@ -103,7 +103,7 @@ To restrict access to your website, enable [GitLab Pages Access Control](pages_a If you're using a self-managed instance (Core, Starter, Premium, or Ultimate), your websites will be published on your own server, according to the -[Pages admin settings](../../../administration/pages/index.md) chosen by your sysadmin, +[Pages settings](../../../administration/pages/index.md) chosen by your sysadmin, who can make them public or internal. ## Pages examples diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 6dbc12cc2ec..5a284bf57c3 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,7 +1,7 @@ --- stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 --- # Exploring GitLab Pages @@ -280,4 +280,4 @@ No, you don't. You can create your project first and it will be accessed under ## Known issues -For a list of known issues, visit GitLab's [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages). +For a list of known issues, visit the GitLab [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages). diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index 13ea57939f8..f2b75354bf8 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -1,19 +1,19 @@ --- stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 description: "How to secure GitLab Pages websites with Let's Encrypt (manual process, deprecated)." --- # Let's Encrypt for GitLab Pages (manual process, deprecated) -CAUTION: **Warning:** +WARNING: This method is still valid but was **deprecated** in favor of the [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) introduced in GitLab 12.1. If you have a GitLab Pages website served under your own domain, -you might want to secure it with a SSL/TSL certificate. +you might want to secure it with a SSL/TLS certificate. [Let's Encrypt](https://letsencrypt.org) is a free, automated, and open source Certificate Authority. @@ -67,7 +67,7 @@ might be slightly different. Follow the sudo certbot certonly -a manual -d example.com --register-unsafely-without-email ``` - TIP: **Tip:** + NOTE: Read through CertBot's documentation on their [command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options). diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index b3705a5835a..9d17277fe9e 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -1,8 +1,8 @@ --- type: reference, howto stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 Pages Access Control diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 60fbf368061..8c189614102 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -1,7 +1,7 @@ --- stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 redirects for GitLab Pages @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4 behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/367) in GitLab 13.5. -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. In GitLab Pages, you can configure rules to forward one URL to another using diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index c23eaebcbe9..cf5f33534cd 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -3,3 +3,6 @@ redirect_to: '../../../ci/pipelines/job_artifacts.md' --- This document was moved to [another location](../../../ci/pipelines/job_artifacts.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/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md index a92464d6817..52352a29c5a 100644 --- a/doc/user/project/pipelines/schedules.md +++ b/doc/user/project/pipelines/schedules.md @@ -3,3 +3,6 @@ redirect_to: '../../../ci/pipelines/schedules.md' --- This document was moved to [another location](../../../ci/pipelines/schedules.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/pipelines/settings.md b/doc/user/project/pipelines/settings.md index af4cbe13aba..f19f28743a8 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -3,3 +3,6 @@ redirect_to: '../../../ci/pipelines/settings.md' --- This document was moved to [another location](../../../ci/pipelines/settings.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/protected_branches.md b/doc/user/project/protected_branches.md index 7265fd330e3..5754a3b7a9d 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -21,8 +21,8 @@ By default, a protected branch does four simple things: - It prevents **anyone** from force pushing to the branch. - It prevents **anyone** from deleting the branch. -NOTE: **Note:** -A GitLab admin is allowed to push to the protected branches. +NOTE: +A GitLab administrator is allowed to push to the protected branches. See the [Changelog](#changelog) section for changes over time. @@ -74,6 +74,33 @@ dropdown list in the "Already protected" area. If you don't choose any of those options while creating a protected branch, they are set to "Maintainers" by default. +### Allow Deploy Keys to push to a protected branch + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30769) in GitLab 13.7. +> - This feature is being selectively deployed in GitLab.com 13.7, and may not be available for all users. + +You can allow specific machines to access protected branches in your repository with +[Deploy Keys](deploy_keys/index.md). This can be useful for your CI/CD workflow, +for example. + +Deploy keys can be selected in the **Allowed to push** dropdown when: + +- Defining a protected branch. +- Updating an existing branch. + +Select a deploy key to allow the owner of the key to push to the chosen protected branch, +even if they aren't a member of the related project. The owner of the selected deploy +key must have at least read access to the given project. + +For a deploy key to be selectable: + +- It must be [enabled for your project](deploy_keys/index.md#how-to-enable-deploy-keys). +- It must have [write access](deploy_keys/index.md#deploy-keys-permissions) to your project repository. + +Deploy Keys are not available in the **Allowed to merge** dropdown. + + + ## Restricting push and merge access to certain users **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.11. @@ -143,7 +170,7 @@ From time to time, it may be required to delete or clean up branches that are protected. User with [Maintainer permissions](../permissions.md) and up can manually delete protected -branches via GitLab's web interface: +branches via the GitLab web interface: 1. Visit **Repository > Branches** 1. Click on the delete icon next to the branch you wish to delete @@ -197,6 +224,10 @@ for details about the pipelines security model. ## Changelog +**13.5** + +- [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769). + **11.9** - [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) by Developers (and users with higher permission levels) through the API and the user interface. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 5dd2a72c91e..7e09c526312 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index db9e2f270e0..8af4307c013 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -17,7 +17,7 @@ Currently, there are push options available for: - [Skipping CI jobs](#push-options-for-gitlab-cicd) - [Merge requests](#push-options-for-merge-requests) -NOTE: **Note:** +NOTE: Git push options are only available with Git 2.10 or newer. For Git versions 2.10 to 2.17 use `--push-option`: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 46db7293711..9f849051f40 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -2,7 +2,7 @@ type: reference stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > quick actions when updating the description of issues, epics, and merge requests. 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 GitLab's UI. +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. @@ -34,6 +34,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/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. | diff --git a/doc/user/project/releases.md b/doc/user/project/releases.md index baa7a295273..6dd5a6f0b0d 100644 --- a/doc/user/project/releases.md +++ b/doc/user/project/releases.md @@ -3,3 +3,6 @@ redirect_to: 'releases/index.md' --- This document was moved to [another location](releases/index.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/releases/index.md b/doc/user/project/releases/index.md index 674fe8b22b8..7b412270938 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -1,8 +1,8 @@ --- type: reference, howto stage: Release -group: Release Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +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 --- # Releases @@ -79,6 +79,16 @@ To create a new release through the GitLab UI: [release notes](#release-notes-description), or [assets links](#links). 1. Click **Create release**. +### Create release from GitLab CI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19298) in GitLab 12.7. + +You can [create a release directly from the GitLab CI pipeline](../../../ci/yaml/README.md#release) +by using a `release` node in the job definition. + +The release is created only if the job processes without error. If the Rails API returns an error +during release creation, the release job fails. + ### Schedule a future release > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38105) in GitLab 12.1. @@ -213,7 +223,7 @@ To set a deploy freeze window in the UI, complete these steps:  -CAUTION: **Caution:** +WARNING: To edit or delete a deploy freeze, use the [Freeze Periods API](../../../api/freeze_periods.md). If a project contains multiple freeze periods, all periods apply. If they overlap, the freeze covers the @@ -460,7 +470,7 @@ In the API: > [Introduced](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/6) in GitLab 12.10. The Release CLI is a command-line tool for managing GitLab Releases from the command line or from -GitLab's CI/CD configuration file, `.gitlab-ci.yml`. +the GitLab CI/CD configuration file, `.gitlab-ci.yml`. With it, you can create, update, modify, and delete releases right through the terminal. diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index a937b6ed959..ffd4b383bcb 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: concepts, howto --- diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 99319efbb7f..4f996df5fef 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' --- @@ -40,7 +40,7 @@ the `app/controllers/admin/deploy_keys_controller.rb` file. Using a fuzzy search, we start by typing letters that get us closer to the file. -TIP: **Tip:** +NOTE: To narrow down your search, include `/` in your search terms.  diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index b0aa7569579..75e1aea632f 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/workflow/forking_workflow.html' --- @@ -26,18 +26,18 @@ Forking a project is, in most cases, a two-step process. 1. Click a namespace to fork to. Only namespaces you have Developer and higher [permissions](../../permissions.md) for are shown. - NOTE: **Note:** + NOTE: The project path must be unique within the namespace.  The fork is created. The permissions you have in the namespace are the permissions you will have in the fork. -CAUTION: **Caution:** +WARNING: In GitLab 12.6 and later, when project owners [reduce a project's visibility](../../../public_access/public_access.md#reducing-visibility), it **removes the relationship** between a project and all its forks. -CAUTION: **Caution:** +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 @@ -52,7 +52,7 @@ The main difference is that with repository mirroring your remote fork will be a Without mirroring, to work locally you'll have to use `git pull` to update your local repository with the upstream project, then push the changes back to your fork to update it. -CAUTION: **Caution:** +WARNING: With mirroring, before approving a merge request, you'll likely be asked to sync; hence 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/). @@ -63,7 +63,7 @@ When you are ready to send your code back to the upstream project, [create a merge request](../merge_requests/creating_merge_requests.md). For **Source branch**, choose your forked project's branch. For **Target branch**, choose the original project's branch. -NOTE: **Note:** +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.  diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index a423f58ba21..4322c79daa7 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto description: "Documentation on Git file blame." --- diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 6cc05d2192f..51cc6bb3483 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto description: "Documentation on Git file history." --- diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 646d708d896..57e9d814c95 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: concepts, howto --- @@ -15,7 +15,7 @@ commits are labeled **Verified** if the identity of the committer can be verified. To verify the identity of a committer, GitLab requires their public GPG key. -NOTE: **Note:** +NOTE: The term GPG is used for all OpenPGP/PGP/GPG related material and implementations. @@ -53,7 +53,7 @@ started: gpg --full-gen-key ``` - NOTE: **Note:** + NOTE: In some cases like Gpg4win on Windows and other macOS versions, the command here may be `gpg --gen-key`. @@ -142,7 +142,7 @@ started: ## Adding a GPG key to your account -NOTE: **Note:** +NOTE: Once you add a key, you cannot edit it, only remove it. In case the paste didn't work, you'll have to remove the offending key and re-add it. diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 40bf40a3dba..e1d84baec4d 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- @@ -48,7 +48,7 @@ to your repository's root. **From the user interface:** -GitLab's UI allows you to perform lots of Git commands without having to +The GitLab UI allows you to perform lots of Git commands without having to touch the command line. Even if you use the command line regularly, sometimes it's easier to do so [via GitLab UI](web_editor.md): @@ -67,7 +67,7 @@ To get started with the command line, please read through the ### Find files -Use GitLab's [file finder](file_finder.md) to search for files in a repository. +Use the GitLab [file finder](file_finder.md) to search for files in a repository. ### Supported markup languages and extensions @@ -141,7 +141,7 @@ their filenames include `openapi` or `swagger` and their extension is `yaml`, Then, to render them: -1. Navigate to the OpenAPI file in your repository in GitLab's UI. +1. Navigate to the OpenAPI file in your repository in the GitLab UI. 1. Click the "Display OpenAPI" button which is located between the "Display source" and "Edit" buttons (when an OpenAPI file is found, it replaces the "Display rendered file" button). @@ -189,7 +189,7 @@ updated every 15 minutes at most, so may not reflect recent activity. The displa The project size may differ slightly from one instance to another due to compression, housekeeping, and other factors. -[Repository size limit](../../admin_area/settings/account_and_limit_settings.md) may be set by admins. +[Repository size limit](../../admin_area/settings/account_and_limit_settings.md) may be set by administrators. GitLab.com's repository size limit [is set by GitLab](../../gitlab_com/index.md#account-and-limit-settings). ## Contributors diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 69a32841981..91fe9049b53 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- # Jupyter Notebook Files diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 9f4dfe54c47..fb798738160 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -1,7 +1,7 @@ --- stage: Create group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- @@ -18,12 +18,12 @@ We **recommend [`git filter-repo`](https://github.com/newren/git-filter-repo/blo over [`git filter-branch`](https://git-scm.com/docs/git-filter-branch) and [BFG](https://rtyley.github.io/bfg-repo-cleaner/). -DANGER: **Warning:** +WARNING: Rewriting repository history is a destructive operation. Make sure to back up your repository before you begin. The best way back up a repository is to [export the project](../settings/import_export.md#exporting-a-project-and-its-data). -NOTE: **Note:** +NOTE: Git LFS files can only be removed by an Administrator using a [Rake task](../../../raketasks/cleanup.md). Removal of this limitation [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/223621). @@ -87,7 +87,7 @@ download all the advertised refs. git push origin --force 'refs/heads/*' ``` - [Protected branches](../protected_branches.md) will cause this to fail. To proceed, you must + [Protected branches](../protected_branches.md) cause this to fail. To proceed, you must remove branch protection, push, and then re-enable protected branches. 1. To remove large files from tagged releases, force push your changes to all tags on GitLab: @@ -96,7 +96,7 @@ download all the advertised refs. git push origin --force 'refs/tags/*' ``` - [Protected tags](../protected_tags.md) will cause this to fail. To proceed, you must remove tag + [Protected tags](../protected_tags.md) cause this to fail. To proceed, you must remove tag protection, push, and then re-enable protected tags. 1. To prevent dead links to commits that no longer exist, push the `refs/replace` created by `git filter-repo`. @@ -109,7 +109,7 @@ download all the advertised refs. 1. Run a [repository cleanup](#repository-cleanup). -NOTE: **Note:** +NOTE: Project statistics are cached for performance. You may need to wait 5-10 minutes to see a reduction in storage utilization. @@ -131,7 +131,7 @@ To purge files from GitLab storage: tar xzf project-backup.tar.gz ``` - This will contain a `project.bundle` file, which was created by + This contains a `project.bundle` file, which was created by [`git bundle`](https://git-scm.com/docs/git-bundle). 1. Clone a fresh copy of the repository from the bundle: @@ -141,12 +141,12 @@ To purge files from GitLab storage: ``` 1. Using `git filter-repo`, purge any files from the history of your repository. Because we are - trying to remove internal refs, we will rely on the `commit-map` produced by each run to tell us + trying to remove internal refs, we rely on the `commit-map` produced by each run to tell us which internal refs to remove. - NOTE: **Note:** + NOTE: `git filter-repo` creates a new `commit-map` file every run, and overwrite the `commit-map` from - the previous run. You will need this file from **every** run. Do the next step every time you run + the previous run. You need this file from **every** run. Do the next step every time you run `git filter-repo`. To purge all large files, the `--strip-blobs-bigger-than` option can be used: @@ -178,7 +178,7 @@ To purge files from GitLab storage: git push origin --force 'refs/heads/*' ``` - [Protected branches](../protected_branches.md) will cause this to fail. To proceed, you must + [Protected branches](../protected_branches.md) cause this to fail. To proceed, you must remove branch protection, push, and then re-enable protected branches. 1. To remove large files from tagged releases, force push your changes to all tags on GitLab: @@ -187,7 +187,7 @@ To purge files from GitLab storage: git push origin --force 'refs/tags/*' ``` - [Protected tags](../protected_tags.md) will cause this to fail. To proceed, you must remove tag + [Protected tags](../protected_tags.md) cause this to fail. To proceed, you must remove tag protection, push, and then re-enable protected tags. 1. To prevent dead links to commits that no longer exist, push the `refs/replace` created by `git filter-repo`. @@ -202,19 +202,19 @@ To purge files from GitLab storage: ## Repository cleanup -NOTE: **Note:** -Safely cleaning the repository requires it to be made read-only for the duration -of the operation. This happens automatically, but submitting the cleanup request -will fail if any writes are ongoing, so cancel any outstanding `git push` -operations before continuing. - > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19376) in GitLab 11.6. -Repository cleanup allows you to upload a text file of objects and GitLab will remove internal Git +Repository cleanup allows you to upload a text file of objects and GitLab removes internal Git references to these objects. You can use [`git filter-repo`](https://github.com/newren/git-filter-repo) to produce a list of objects (in a `commit-map` file) that can be used with repository cleanup. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45058) in GitLab 13.6, +safely cleaning the repository requires it to be made read-only for the duration +of the operation. This happens automatically, but submitting the cleanup request +fails if any writes are ongoing, so cancel any outstanding `git push` +operations before continuing. + To clean up a repository: 1. Go to the project for the repository. @@ -230,25 +230,30 @@ To clean up a repository: 1. Click **Start cleanup**. -This will: +This: -- Remove any internal Git references to old commits. -- Run `git gc` against the repository to remove unreferenced objects. Repacking your repository will temporarily - cause the size of your repository to increase significantly, because the old pack files are not removed until the +- Removes any internal Git references to old commits. +- Runs `git gc --prune=30.minutes.ago` against the repository to remove unreferenced objects. Repacking your repository temporarily + causes the size of your repository to increase significantly, because the old pack files are not removed until the new pack files have been created. -- Unlink any unused LFS objects currently attached to your project, freeing up storage space. -- Recalculate the size of your repository on disk. +- Unlinks any unused LFS objects currently attached to your project, freeing up storage space. +- Recalculates the size of your repository on disk. + +GitLab sends an email notification with the recalculated repository size after the cleanup has completed. -You will receive an email notification with the recalculated repository size after the cleanup has completed. +If the repository size does not decrease, this may be caused by loose objects +being kept around because they were referenced in a Git operation that happened +in the last 30 minutes. Try re-running these steps once the repository has been +dormant for at least 30 minutes. When using repository cleanup, note: - Project statistics are cached. You may need to wait 5-10 minutes to see a reduction in storage utilization. -- Housekeeping prunes loose objects older than 2 weeks. This means objects added in the last 2 weeks - will not be removed immediately. If you have access to the - [Gitaly](../../../administration/gitaly/index.md) server, you may run `git gc --prune=now` to +- The cleanup prunes loose objects older than 30 minutes. This means objects added or referenced in the last 30 minutes + are not be removed immediately. If you have access to the + [Gitaly](../../../administration/gitaly/index.md) server, you may slip that delay and run `git gc --prune=now` to prune all loose objects immediately. -- This process will remove some copies of the rewritten commits from GitLab's cache and database, +- This process removes some copies of the rewritten commits from the GitLab cache and database, but there are still numerous gaps in coverage and some of the copies may persist indefinitely. [Clearing the instance cache](../../../administration/raketasks/maintenance.md#clear-redis-cache) may help to remove some of them, but it should not be depended on for security purposes! @@ -289,8 +294,8 @@ size of the repository, because the earlier commits and blobs still exist. Inste history. We recommend the open-source community-maintained tool [`git filter-repo`](https://github.com/newren/git-filter-repo). -NOTE: **Note:** -Until `git gc` runs on the GitLab side, the "removed" commits and blobs will still exist. You also +NOTE: +Until `git gc` runs on the GitLab side, the "removed" commits and blobs still exist. You also must be able to push the rewritten history to GitLab, which may be impossible if you've already exceeded the maximum size limit. @@ -302,9 +307,9 @@ increased, your only option is to: 1. Prune all the unneeded stuff locally. 1. Create a new project on GitLab and start using that instead. -CAUTION: **Caution:** +WARNING: This process is not suitable for removing sensitive data like password or keys from your repository. -Information about commits, including file content, is cached in the database, and will remain +Information about commits, including file content, is cached in the database, and remain visible even after they have been removed from the repository. ## Troubleshooting diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 1f9835f4f59..96694a9e954 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- @@ -11,8 +11,7 @@ Repository mirroring allows for mirroring of repositories to and from external s used to mirror branches, tags, and commits between repositories. A repository mirror at GitLab will be updated automatically. You can also manually trigger an update -at most once every 5 minutes. Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/237891) -for discussions on how to potentially reduce the delay. +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). ## Overview @@ -30,7 +29,7 @@ Users with at least [Developer access](../../permissions.md) to the project can immediate update, unless: - The mirror is already being updated. -- 5 minutes haven't elapsed since its last update. +- The [limit for pull mirroring interval seconds](../../../administration/instance_limits.md#pull-mirroring-interval) has not elapsed since its last update. For security reasons, in [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/27166), the URL to the original repository is only displayed to users with @@ -117,14 +116,14 @@ skipped, allowing `master` and `stable` to be updated. The mirror status will reflect that `develop` has diverged and was skipped, and be marked as a failed update. -NOTE: **Note:** +NOTE: After the mirror is created, this option can currently only be modified via the [API](../../../api/remote_mirrors.md). ## Setting up a push mirror from GitLab to GitHub **(CORE)** To set up a mirror from GitLab to GitHub, you need to follow these steps: -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. 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. 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. @@ -137,11 +136,11 @@ The repository will push soon. To force a push, click the **Update now** (**{ret 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. -Each new AWS Codepipeline needs significant AWS infrastructure setup. It also requires an individual pipeline per branch. +Each new AWS CodePipeline needs significant AWS infrastructure setup. It also requires an individual pipeline per branch. If AWS CodeDeploy is the final step of a CodePipeline, you can, instead, leverage GitLab CI/CD pipelines and simply use the AWS CLI in the final job in `.gitlab-ci.yml` to deploy to CodeDeploy. -NOTE: **Note:** +NOTE: GitLab-to-AWS-CodeCommit push mirroring cannot use SSH authentication until [GitLab issue 34014](https://gitlab.com/gitlab-org/gitlab/-/issues/34014) is resolved. To set up a mirror from GitLab to AWS CodeCommit: @@ -177,7 +176,7 @@ To set up a mirror from GitLab to AWS CodeCommit: 1. Click the **Security credentials** tab. 1. Under **HTTPS Git credentials for AWS CodeCommit** click **Generate credentials**. - NOTE: **Note:** + NOTE: This Git user ID and password is specific to communicating with CodeCommit. Do not confuse it with the IAM user ID or AWS keys of this user. @@ -256,7 +255,7 @@ Changes pushed to the upstream repository will be pulled into the GitLab reposit - Automatically within a certain period of time. - When a [forced update](#forcing-an-update) is initiated. -CAUTION: **Caution:** +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. @@ -301,7 +300,7 @@ To get started: 1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section. 1. Enter an `ssh://` URL for mirroring. -NOTE: **Note:** +NOTE: SCP-style URLs (that is, `git@example.com:group/project.git`) are not supported at this time. Entering the URL adds two buttons to the page: @@ -320,7 +319,7 @@ 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/github/authenticating-to-github/githubs-ssh-key-fingerprints) +- [GitHub](https://docs.github.com/en/free-pro-team@latest/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/) @@ -337,7 +336,7 @@ $ cat /etc/ssh/ssh_host*pub | ssh-keygen -E md5 -l -f - 2048 MD5:3f:72:be:3d:62:03:5c:62:83:e8:6e:14:34:3a:85:1d root@example.com (RSA) ``` -NOTE: **Note:** +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 @@ -364,7 +363,7 @@ 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 key to keep the mirror running. -NOTE: **Note:** +NOTE: The generated keys are stored in the GitLab database, not in the filesystem. Therefore, SSH public key authentication for mirrors cannot be used in a pre-receive hook. @@ -375,7 +374,7 @@ SSH public key authentication for mirrors cannot be used in a pre-receive hook. You can choose to always update your local branches with remote versions, even if they have diverged from the remote. -CAUTION: **Caution:** +WARNING: For mirrored branches, enabling this option results in the loss of local changes. To use this option, check the **Overwrite diverged branches** box when creating a repository mirror. @@ -421,7 +420,7 @@ update button which is available on the **Mirroring repositories** section of th ## Bidirectional mirroring **(STARTER)** -CAUTION: **Caution:** +WARNING: Bidirectional mirroring may cause conflicts. If you configure a GitLab repository to both pull from, and push to, the same remote source, there @@ -464,7 +463,7 @@ To do this: ### Preventing conflicts using a `pre-receive` hook -CAUTION: **Warning:** +WARNING: The solution proposed will negatively impact the performance of Git push operations because they will be proxied to the upstream Git repository. @@ -547,7 +546,7 @@ Note that this sample has a few limitations: ### Mirroring with Perforce Helix via Git Fusion **(STARTER)** -CAUTION: **Warning:** +WARNING: Bidirectional mirroring should not be used as a permanent configuration. Refer to [Migrating from Perforce Helix](../import/perforce.md) for alternative migration approaches. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 5b82cdbd9e9..24bfeee5e7f 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -32,7 +32,7 @@ When you are satisfied with your new file, click **Commit Changes** at the botto ### Shortcuts You can use handy shortcuts when editing a file through the Web Editor, which are the same as -the WEB IDE's. For details, see the documentation for [Command Palette](../web_ide/index.md#command-palette). +the Web IDE's. For details, see the documentation for [Command Palette](../web_ide/index.md#command-palette). ### Template dropdowns @@ -53,7 +53,7 @@ has already been created, which creates a link to the license itself.  -NOTE: **Note:** +NOTE: The **Set up CI/CD** button will not appear on an empty repository. You have to at least add a file in order for the button to show up. @@ -94,7 +94,7 @@ the target branch. Click **Create directory** to finish. ## Create a new branch -There are multiple ways to create a branch from GitLab's web interface. +There are multiple ways to create a branch from the GitLab web interface. ### Create a new branch from an issue @@ -106,7 +106,7 @@ The new branch, and later its merge request, will be marked as related to this i Once merged, the MR will automatically close the issue. You can see a **Create merge request** dropdown below the issue description. -NOTE: **Note:** +NOTE: You won't see the **Create merge request** button if there is already a branch with the same name or a referenced merge request or your project has an active fork relationship. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 9b420d84f50..639bca0d354 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: concepts, howto --- @@ -28,10 +28,10 @@ For a commit or tag to be *verified* by GitLab: which is usually up to three years. - The signing time is equal or later than commit time. -NOTE: **Note:** +NOTE: Certificate revocation lists are checked on a daily basis via background worker. -NOTE: **Note:** +NOTE: Self signed certificates without `authorityKeyIdentifier`, `subjectKeyIdentifier`, and `crlDistributionPoints` are not supported. We recommend using certificates from a PKI that are in line with diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index f533f8807d2..9d75c4ab071 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Plan group: Certify -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Requirements Management **(ULTIMATE)** @@ -30,9 +30,11 @@ For an overview, see [GitLab 12.10 Introduces Requirements Management](https://w A paginated list of requirements is available in each project, and there you can create a new requirement. +Users with Reporter or higher [permissions](../../permissions.md) can create requirements. + To create a requirement: -1. From your project page, go to **{requirements}** **Requirements**. +1. From your project page, go to **Requirements**. 1. Select **New requirement**. 1. Enter a title and description and select **Create requirement**. @@ -54,8 +56,9 @@ next to the requirement title. > The ability to mark a requirement as Satisfied [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218607) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.5. -You can edit a requirement (if you have the necessary privileges) from the requirements -list page. +You can edit a requirement from the requirements list page. + +Users with Reporter or higher [permissions](../../permissions.md) can edit requirements. To edit a requirement: @@ -66,9 +69,11 @@ To edit a requirement: ## Archive a requirement -You can archive an open requirement (if you have the necessary privileges) while +You can archive an open requirement while you're in the **Open** tab. +Users with Reporter or higher [permissions](../../permissions.md) can archive requirements. + To archive a requirement, select **Archive** (**{archive}**). As soon as a requirement is archived, it no longer appears in the **Open** tab. @@ -77,6 +82,8 @@ As soon as a requirement is archived, it no longer appears in the **Open** tab. You can view the list of archived requirements in the **Archived** tab. +Users with Reporter or higher [permissions](../../permissions.md) can reopen archived requirements. +  To reopen an archived requirement, select **Reopen**. @@ -94,7 +101,7 @@ You can search for a requirement from the requirements list page based on the fo To search for a requirement: -1. In a project, go to **{requirements}** **Requirements > List**. +1. 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. Press <kbd>Enter</kbd> on your keyboard to filter the list. @@ -188,3 +195,65 @@ requirements_confirmation: reports: requirements: tmp/requirements.json ``` + +## Import requirements from a CSV file + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/246857) in GitLab 13.7. + +You can import requirements to a project by uploading a CSV file with the columns +`title` and `description`. + +The user uploading the CSV file will be set as the author of the imported requirements. + +Users with Reporter or higher [permissions](../../permissions.md) can import requirements. + +### Import the file + +Before you import your file: + +- Consider importing a test file containing only a few requirements. There is no way to undo a large + import without using the GitLab API. +- Ensure your CSV file meets the [file format](#csv-file-format) requirements. + +To import requirements: + +1. Navigate to a project's Requirements page. + - If the project already has existing requirements, click the import icon (**{import}**) at the + top right. + - For a project without any requirements, click **Import CSV** in the middle of the page. +1. Select the file and click **Import requirements**. + +The file is processed in the background and a notification email is sent +to you after the import is complete. + +### CSV file format + +When importing requirements from a CSV file, it must be formatted in a certain way: + +- **Header row:** CSV files must include the following headers: + `title` and `description`. The headers are case insensitive. +- **Columns:** data from columns other than `title` and `description` is not imported. +- **Separators:** the column separator is automatically detected from the header row. + Supported separator characters are: commas (`,`), semicolons (`;`), and tabs (`\t`). + The row separator can be either `CRLF` or `LF`. +- **Double-quote character:** the double-quote (`"`) character is used to quote fields, + enabling the use of the column separator in a field (see the third line in the + sample CSV data below). To insert a double-quote (`"`) in a quoted + field, use two double-quote characters in succession (`""`). +- **Data rows:** below the header row, succeeding rows must follow the same column + order. The title text is required, while the description is optional and can be left empty. + +Sample CSV data: + +```plaintext +title,description +My Requirement Title,My Requirement Description +Another Title,"A description, with a comma" +"One More Title","One More Description" +``` + +### File size + +The limit depends on the configuration value of Max Attachment Size for the GitLab instance. + +For GitLab.com, it is set to 10 MB. diff --git a/doc/user/project/security_dashboard.md b/doc/user/project/security_dashboard.md index a3da1ec97d3..d9440e8deea 100644 --- a/doc/user/project/security_dashboard.md +++ b/doc/user/project/security_dashboard.md @@ -3,3 +3,6 @@ redirect_to: '../application_security/security_dashboard/index.md' --- This document was moved to [another location](../application_security/security_dashboard/index.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/service_desk.md b/doc/user/project/service_desk.md index 34a075df990..4f3ca12c582 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -1,10 +1,10 @@ --- stage: Plan group: Certify -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 Desk +# Service Desk **(CORE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/149) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/214839) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.0. @@ -59,7 +59,7 @@ users will only see the thread through email. ## Configuring Service Desk -NOTE: **Note:** +NOTE: Service Desk is enabled on GitLab.com. You can skip step 1 below; you only need to enable it per project. @@ -76,7 +76,7 @@ Follow these steps to do so: address's format. The older format is still supported, however, allowing existing aliases or contacts to continue working. - DANGER: **Warning:** + WARNING: This email address can be used by anyone to create an issue on this project, whether or not they have access to your GitLab instance. We recommend **putting this behind an alias** so it can be changed if needed, and **[enabling Akismet](../../integration/akismet.md)** on your GitLab @@ -129,10 +129,12 @@ this name in the `From` header. The default display name is `GitLab Support Bot` ### Using custom email address **(CORE ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. - -NOTE: **Note:** -This feature is disabled by default. For steps to enable it, see [Enable custom email address](#enable-custom-email-address). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. +> - It was [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) on GitLab 13.7. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-custom-email-address). **(CORE ONLY)** If the `service_desk_email` feature flag is enabled in your configuration, then it's possible to create Service Desk issues by sending emails to the @@ -198,18 +200,27 @@ In this case, suppose the `mygroup/myproject` project Service Desk settings has suffix set to `support`, and a user sends an email to `project_contact+mygroup-myproject-support@example.com`. As a result, a new Service Desk issue is created from this email in the `mygroup/myproject` project. -#### Enable custom email address +The configuration options are the same as for configuring +[incoming email](../../administration/incoming_email.md#set-it-up). + +#### Disable custom email address **(CORE ONLY)** + +Service Desk custom email is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can opt to disable it. -This feature comes with the `service_desk_custom_address` feature flag disabled by default. -To turn on the feature, ask a GitLab administrator with Rails console access to run the following -command: +To enable it: ```ruby Feature.enable(:service_desk_custom_address) ``` -The configuration options are the same as for configuring -[incoming email](../../administration/incoming_email.md#set-it-up). +To disable it: + +```ruby +Feature.disable(:service_desk_custom_address) +``` ## Using Service Desk diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 3e493f02392..53233cc347e 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +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 --- @@ -42,7 +42,7 @@ Note the following: - Exports are stored in a temporary [shared directory](../../../development/shared_files.md) and are deleted every 24 hours by a specific worker. - Group members are exported as project members, as long as the user has - maintainer or admin access to the group where the exported project lives. + maintainer or administrator access to the group where the exported project lives. - Project members with owner access will be imported as maintainers. - Imported users can be mapped by their primary email on self-managed instances, if an administrative user (not an owner) does the import. Otherwise, a supplementary comment is left to mention that the original author and @@ -51,6 +51,9 @@ Note the following: then new branches associated with such merge requests will be created within a project during the import/export. Thus, the number of branches in the exported project could be bigger than in the original project. +- Deploy keys allowed to push to protected branches are not exported. Therefore, + you will need to recreate this association by first enabling these deploy keys in your + imported project and then updating your protected branches accordingly. ## Version history @@ -114,8 +117,9 @@ The following items will be exported: - LFS objects - Issue boards - Pipelines history +- Push Rules -The following items will NOT be exported: +The following items will **not** be exported: - Build traces and artifacts - Container registry images @@ -123,10 +127,9 @@ The following items will NOT be exported: - Webhooks - Any encrypted tokens - Merge Request Approvers -- Push Rules - Awards -NOTE: **Note:** +NOTE: For more details on the specific data persisted in a project export, see the [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/import_export/project/import_export.yml) file. @@ -170,14 +173,14 @@ To export a project and its data, follow these steps: 1. Click on **Import project** to begin importing. Your newly imported project page will appear soon. -NOTE: **Note:** +NOTE: If use of the `Internal` visibility level [is restricted](../../../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects), all imported projects are given the visibility of `Private`. -NOTE: **Note:** +NOTE: The maximum import file size can be set by the Administrator, default is 50MB. -As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin UI](../../admin_area/settings/account_and_limit_settings.md). +As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md). ### Project import status @@ -188,12 +191,14 @@ As described in the API documentation, the query may return an import error or e If you have a larger project, consider using a Rake task, as described in our [developer documentation](../../../development/import_project.md#importing-via-a-rake-task). -## Rate limits +## Rate Limits + +To help avoid abuse, by default, users are rate limited to: -To help avoid abuse, users are rate limited to: +| Request Type | Limit | +| ---------------- | ---------------------------------------- | +| Export | 6 projects per minute | +| Download export | 1 download per group per minute | +| Import | 6 projects per minute | -| Request Type | Limit | -| ---------------- | ----------------------------------------- | -| Export | 30 projects per 5 minutes | -| Download export | 10 downloads per project every 10 minutes | -| Import | 30 projects per 5 minutes | +Please note that GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) from the defaults. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 4b368fc20d6..41f404de4f2 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -1,13 +1,13 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, index, howto --- # Project settings -NOTE: **Note:** +NOTE: Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) to access a project settings. @@ -31,13 +31,13 @@ The project description also partially supports [standard Markdown](../../markdo You can select a framework label to identify that your project has certain compliance requirements or needs additional oversight. Available labels include: -- GDPR - General Data Protection Regulation -- HIPAA - Health Insurance Portability and Accountability Act -- PCI-DSS - Payment Card Industry-Data Security Standard -- SOC 2 - Service Organization Control 2 -- SOX - Sarbanes-Oxley +- GDPR (General Data Protection Regulation) +- HIPAA (Health Insurance Portability and Accountability Act) +- PCI-DSS (Payment Card Industry-Data Security Standard) +- SOC 2 (Service Organization Control 2) +- SOX (Sarbanes-Oxley) -NOTE: **Note:** +NOTE: Compliance framework labels do not affect your project settings. ### Sharing and permissions @@ -52,7 +52,7 @@ If you set **Project Visibility** to public, you can limit access to some featur to **Only Project Members**. In addition, you can select the option to [Allow users to request access](../members/index.md#project-membership-and-requesting-access). -CAUTION: **Caution:** +WARNING: If you [reduce a project's visibility level](../../../public_access/public_access.md#reducing-visibility), that action unlinks all forks of that project. @@ -68,11 +68,13 @@ Use the switches to enable or disable the following features: | **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your Docker images | | **Git Large File Storage** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs) | | **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality | +| **Analytics** | ✓ | Enables [analytics](../../analytics/) | | **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/) | | **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md) | | **Pages** | ✓ | Allows you to [publish static websites](../pages/) | | **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md) -| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md) +| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md) | +| **Operations Dashboard** | ✓ | Control access to [operations dashboard](../../../operations/index.md) Some features depend on others: @@ -81,7 +83,7 @@ Some features depend on others: - **Issue Boards** - [**Service Desk**](#service-desk) - NOTE: **Note:** + NOTE: When the **Issues** option is disabled, you can still access **Milestones** from merge requests. @@ -186,7 +188,7 @@ Next, to unarchive the project: #### Renaming a repository -NOTE: **Note:** +NOTE: Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) to rename a repository. Not to be confused with a project's name where it can also be changed from the [general project settings](#general-project-settings). @@ -198,8 +200,8 @@ To rename a repository: 1. Navigate to your project's **Settings > General**. 1. Under **Advanced**, click **Expand**. -1. Under "Rename repository", change the "Path" to your liking. -1. Hit **Rename project**. +1. Under **Change path**, update the repository's path. +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 @@ -207,7 +209,7 @@ old URL won't be able to push or pull. Read more about what happens with the #### Transferring an existing project into another namespace -NOTE: **Note:** +NOTE: Only project owners and administrators have the [permissions](../../permissions.md#project-members-permissions) to transfer a project. @@ -229,13 +231,13 @@ Once done, you will be taken to the new project's namespace. At this point, read what happens with the [redirects from the old project to the new one](../index.md#redirects-when-changing-repository-paths). -NOTE: **Note:** +NOTE: GitLab administrators can use the administration interface to move any project to any namespace if needed. #### Delete a project -NOTE: **Note:** +NOTE: Only project owners and administrators have [permissions](../../permissions.md#project-members-permissions) to delete a project. To delete a project: @@ -253,7 +255,7 @@ 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). -CAUTION: **Warning:** +WARNING: The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to [Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. @@ -274,7 +276,7 @@ If you want to use the fork for yourself and don't need to send [merge requests](../merge_requests/index.md) to the upstream project, you can safely remove the fork relationship. -CAUTION: **Caution:** +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. To do so: @@ -283,7 +285,7 @@ To do so: 1. Under **Remove fork relationship**, click the likewise-labeled button. 1. Confirm the action by typing the project's path as instructed. -NOTE: **Note:** +NOTE: Only project owners have the [permissions](../../permissions.md#project-members-permissions) to remove a fork relationship. diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 9f8cf2ff41a..494f0b725e3 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,20 +1,23 @@ --- stage: Manage group: Access -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +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 --- # Project access tokens -NOTE: **Note:** -Project access tokens are supported for self-managed instances on Core and above. They are also supported on GitLab.com Bronze and above. +NOTE: +Project access tokens are supported for self-managed instances on Core and above. They are also supported on GitLab.com Bronze and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0. > - It was [deployed](https://gitlab.com/groups/gitlab-org/-/epics/2587) behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/218722) in GitLab 13.3. -> - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in 13.5. > - It's recommended for production use. +> - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in 13.5 for paid groups only. + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. Project access tokens are scoped to a project and can be used to authenticate with the [GitLab API](../../../api/README.md#personalproject-access-tokens). You can also use project access tokens with Git to authenticate over HTTP. @@ -69,9 +72,39 @@ the following table. | Scope | Description | | ------------------ | ----------- | -| `api` | Grants complete read/write access to the scoped project API. | -| `read_api` | Grants read access to the scoped project API. | +| `api` | Grants complete read/write access to the scoped project API, including the Package Registry](../../packages/package_registry/index.md). | +| `read_api` | Grants read access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | | `read_registry` | Allows read-access (pull) to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | | `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | | `read_repository` | Allows read-only access (pull) to the repository. | | `write_repository` | Allows read-write access (pull, push) to the repository. | + +### 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/slash_commands.md b/doc/user/project/slash_commands.md index 1280524bc9b..5844861c91e 100644 --- a/doc/user/project/slash_commands.md +++ b/doc/user/project/slash_commands.md @@ -3,3 +3,6 @@ redirect_to: 'quick_actions.md' --- This document was moved to [user/project/quick_actions.md](quick_actions.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/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index c2d4c77a469..07f122a7828 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -1,7 +1,7 @@ --- stage: Create -group: Static Site Editor -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +group: Editor +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, how-to description: "The static site editor enables users to edit content on static websites without prior knowledge of the underlying templating language, site architecture or Git commands." --- @@ -11,6 +11,7 @@ description: "The static site editor enables users to edit content on static web > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28758) in GitLab 12.10. > - WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214559) in GitLab 13.0. > - Non-Markdown content blocks uneditable on the WYSIWYG mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216836) in GitLab 13.3. +> - Formatting Markdown [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49052) in GitLab 13.7. Static Site Editor (SSE) enables users to edit content on static websites without prior knowledge of the underlying templating language, site architecture, or @@ -53,10 +54,16 @@ click of a button:  -When an editor submits their changes, in the background, GitLab automatically -creates a new branch, commits their changes, and opens a merge request. The -editor lands directly on the merge request, and then they can assign it to -a colleague for review. +When an editor submits their changes, these are the following actions that GitLab +performs automatically in the background: + +1. Creates a new branch. +1. Commits their changes. + 1. Fixes formatting according to the [Handbook Markdown Style Guide](https://about.gitlab.com/handbook/markdown-guide/) + style guide and add them through another commit. +1. Opens a merge request against the default branch. + +The editor can then navigate to the merge request to assign it to a colleague for review. ## Set up your project @@ -162,7 +169,7 @@ title, layout template, or author, but can be used to pass any kind of metadata generator as the page renders out to HTML. Included at the very top of each data file, the front matter is often formatted as YAML or JSON and requires consistent and accurate syntax. -To edit the front matter from the Static Site Editor you can use the GitLab's regular file editor, +To edit the front matter from the Static Site Editor you can use the GitLab regular file editor, the Web IDE, or easily update the data directly from the WYSIWYG editor: 1. Click the **Page settings** button on the bottom-right to reveal a web form with the data you diff --git a/doc/user/project/status_page/index.md b/doc/user/project/status_page/index.md index 20bb23f1d6b..513c410a6f9 100644 --- a/doc/user/project/status_page/index.md +++ b/doc/user/project/status_page/index.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/incident_management/status_page.md' --- This document was moved to [status_page.md](../../../operations/incident_management/status_page.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/time_tracking.md b/doc/user/project/time_tracking.md index b88e1ed2d37..c94795578ef 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -3,7 +3,7 @@ type: reference disqus_identifier: 'https://docs.gitlab.com/ee/workflow/time_tracking.html' stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Time Tracking @@ -49,7 +49,7 @@ you need to enter an estimate of 3 days, 5 hours and 10 minutes, you would write `/estimate 3d 5h 10m`. Time units that we support are listed at the bottom of this help page. -Every time you enter a new time estimate, any previous time estimates will be +Every time you enter a new time estimate, any previous time estimates are overridden by this new value. There should only be one valid estimate in an issue or a merge request. @@ -59,12 +59,12 @@ To remove an estimation entirely, use `/remove_estimate`. To enter a time spent, use `/spend 3d 5h 10m`. -Every new time spent entry will be added to the current total time spent for the +Every new time spent entry is added to the current total time spent for the issue or the merge request. -You can remove time by entering a negative amount: `/spend -3d` will remove 3 +You can remove time by entering a negative amount: for example, `/spend -3d` removes three days from the total time spent. You can't go below 0 minutes of time spent, -so GitLab will automatically reset the time spent if you remove a larger amount +so GitLab automatically resets the time spent if you remove a larger amount of time compared to the time that was entered already. To remove all the time spent at once, use `/remove_time_spent`. 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 differindex b4b14f1fc7f..6257d78d29e 100644 --- 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 diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 2b9db1c952d..29b24028e48 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, how-to --- @@ -66,7 +66,7 @@ Monaco uses the [Monarch](https://microsoft.github.io/monaco-editor/monarch.html If you are missing Syntax Highlighting support for any language, we prepared a short guide on how to [add support for a missing language Syntax Highlighting.](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/ide/lib/languages/README.md) -NOTE: **Note:** +NOTE: Single file editing is based on the [Ace Editor](https://ace.c9.io). ### Themes @@ -262,8 +262,8 @@ quickly share your project with others. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268288) in GitLab 12.9, third-party assets and libraries required for Live Preview are hosted at `https://sandbox-prod.gitlab-static.net` when it is enabled. However, some libraries are still served from other third-party services which may or may not be desirable in your environment. -The Live Preview feature needs to be enabled in the GitLab instances -admin settings. Live Preview is enabled for all projects on +The Live Preview feature needs to be enabled in the GitLab instance's +Admin Area. Live Preview is enabled for all projects on GitLab.com  @@ -286,9 +286,9 @@ below. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) to GitLab Core in 13.1. -CAUTION: **Warning:** +WARNING: Interactive Web Terminals for the Web IDE is currently in **Beta**. -Shared runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab/-/issues/24674), +GitLab.com shared runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab/-/issues/24674), so you would need to use your own private runner to make use of this feature. [Interactive Web Terminals](../../../ci/interactive_web_terminal/index.md) @@ -313,7 +313,7 @@ terminal blocks the job from finishing for the duration configured in [`[session_server].session_timeout`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) until you close the terminal window. -NOTE: **Note:** +NOTE: Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). The [File Sync](#file-syncing-to-web-terminal) feature is supported on Kubernetes runners only. @@ -394,7 +394,7 @@ File changes in the Web IDE can be synced to a running web terminal. This enables users to test their code changes in a preconfigured terminal environment. -NOTE: **Note:** +NOTE: Only file changes in the Web IDE are synced to the terminal. Changes made in the terminal are **not** synced to the Web IDE. This feature is only available for Kubernetes runners. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index e082e091dec..7802f2ba95e 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Knowledge -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +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, how-to --- @@ -34,7 +34,7 @@ message. ## Creating a new wiki page -NOTE: **Note:** +NOTE: Requires Developer [permissions](../../permissions.md). Create a new page by clicking the **New page** button that can be found @@ -64,7 +64,7 @@ When you're ready, click the **Create page** and the new page will be created. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475) in GitLab 11.3. -Starting with GitLab 11.3, any file that is uploaded to the wiki via GitLab's +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 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 @@ -208,7 +208,7 @@ On the project's Wiki page, there is a right side navigation that renders the fu To customize the sidebar, you can create a file named `_sidebar` to fully replace the default navigation. -CAUTION: **Warning:** +WARNING: Unless you link the `_sidebar` file from your custom nav, to edit it you'll have to access it directly from the browser's address bar by typing: `https://gitlab.com/<namespace>/<project_name>/-/wikis/_sidebar` (for self-managed GitLab instances, replace `gitlab.com` with your instance's URL). @@ -226,4 +226,4 @@ Example for `_sidebar` (using Markdown format): - [Sidebar](_sidebar) ``` -Support for displaying a generated TOC with a custom side navigation is planned. +Support for displaying a generated table of contents with a custom side navigation is planned. |
