diff options
Diffstat (limited to 'doc/user/project')
113 files changed, 1480 insertions, 1587 deletions
diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index e03e5b10236..a5473629d4f 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: -This feature was deprecated in GitLab 14.5. Use [Infrastrucure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) +This feature was deprecated in GitLab 14.5. Use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated) to create new clusters. Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic @@ -19,11 +19,11 @@ Kubernetes Service (EKS). ## Connect an existing EKS cluster If you already have an EKS cluster and want to connect it to GitLab, -use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). +use the [GitLab Agent](../../clusters/agent/index.md). ## Create a new EKS cluster -To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). +To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated). ### How to create a new cluster on EKS through cluster certificates (DEPRECATED) diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index fcf2583d3ab..acc5ed4cb30 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +To connect your cluster to GitLab, use the [GitLab Agent](../../clusters/agent/index.md) instead. If you have an existing Kubernetes cluster, you can add it to a project, group, diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 30be319f2df..99edddeb3e9 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -Use [Infrastrucure as Code](../../infrastructure/clusters/connect/new_gke_cluster.md) +Use [Infrastructure as Code](../../infrastructure/clusters/connect/new_gke_cluster.md) to create a cluster hosted on Google Kubernetes Engine (GKE). Through GitLab, you can create new and connect existing clusters @@ -19,7 +19,7 @@ hosted on Google Kubernetes Engine (GKE). ## Connect an existing GKE cluster If you already have a GKE cluster and want to connect it to GitLab, -use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). +use the [GitLab Agent](../../clusters/agent/index.md). ## Create a new GKE cluster from GitLab diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 49708e3b6aa..a0fca517f2e 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. -To create a new cluster use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). +To create a new cluster use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated). NOTE: Every new Google Cloud Platform (GCP) account receives @@ -29,7 +29,7 @@ in a few clicks. > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. -As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) +As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated) to **safely create new clusters from GitLab**. Creating clusters from GitLab using cluster certificates is still available on the @@ -49,7 +49,7 @@ supports connecting existing clusters using the certificate-based connection met ## Add existing cluster -As of GitLab 14.0, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +As of GitLab 14.0, use the [GitLab Agent](../../clusters/agent/index.md) to connect your cluster to GitLab. Alternatively, you can [add an existing cluster](add_existing_cluster.md) @@ -57,7 +57,7 @@ through the certificate-based method, but we don't recommend using this method f ## Configure your cluster -As of GitLab 14.0, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +As of GitLab 14.0, use the [GitLab Agent](../../clusters/agent/index.md) to configure your cluster. ## Disable a cluster diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index 510aad821cf..4e00ae0dd07 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +To connect your cluster to GitLab, use the [GitLab Agent](../../clusters/agent/index.md) instead. When creating a cluster in GitLab, you are asked if you would like to create either: diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index c3a71ec8585..e89ce12b35e 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). +To connect your cluster to GitLab, use the [GitLab Agent](../../clusters/agent/index.md). To deploy with the Agent, use the [CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md). A Kubernetes cluster can be the destination for a deployment job. If diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index ad378be2d9a..686b3026b2c 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Kubernetes Agent](../../../user/clusters/agent/index.md). +To connect your cluster to GitLab, use the [GitLab Agent](../../../user/clusters/agent/index.md). To manage applications, use the [Cluster Project Management Template](../../../user/clusters/management_project_template.md). You can choose to allow GitLab to manage your cluster for you. If your cluster diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index c16c6446acd..dc37060593c 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. To connect clusters to GitLab, use the -[GitLab Kubernetes Agent](../../clusters/agent/index.md). +[GitLab Agent](../../clusters/agent/index.md). [Project-level](../../infrastructure/clusters/connect/index.md#cluster-levels-deprecated) Kubernetes clusters allow you to connect a Kubernetes cluster to a project in GitLab. diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index 540907bf915..12527853b40 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: Using multiple Kubernetes clusters for a single project **with cluster certificates** was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect clusters to GitLab, use the [GitLab Kubernetes Agent](../../../user/clusters/agent/index.md). +To connect clusters to GitLab, use the [GitLab Agent](../../../user/clusters/agent/index.md). You can associate more than one Kubernetes cluster to your project. That way you can have different clusters for different environments, diff --git a/doc/user/project/clusters/protect/container_host_security/index.md b/doc/user/project/clusters/protect/container_host_security/index.md index c005ce64bb5..98ba4a1f84d 100644 --- a/doc/user/project/clusters/protect/container_host_security/index.md +++ b/doc/user/project/clusters/protect/container_host_security/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w NOTE: In GitLab 14.5, using a certificate to connect GitLab to a Kubernetes cluster is [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). You can continue using Container Host Security, even though it relies on this certificate-based -method. The work to allow all aspects of Container Host Security to function through the [GitLab Kubernetes Agent](../../../../clusters/agent/index.md) +method. The work to allow all aspects of Container Host Security to function through the [GitLab Agent](../../../../clusters/agent/index.md) instead of the certificate-based method can be tracked [in this GitLab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/299350). Container Host Security in GitLab provides Intrusion Detection and Prevention capabilities that can diff --git a/doc/user/project/clusters/protect/container_network_security/index.md b/doc/user/project/clusters/protect/container_network_security/index.md index eb15675da19..06dc6b24620 100644 --- a/doc/user/project/clusters/protect/container_network_security/index.md +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w NOTE: In GitLab 14.5, using a certificate to connect GitLab to a Kubernetes cluster is [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). You can continue using Container Network Security, even though it relies on this certificate-based -method. The work to allow all aspects of Container Network Security to function through the [GitLab Kubernetes Agent](../../../../clusters/agent/index.md) +method. The work to allow all aspects of Container Network Security to function through the [GitLab Agent](../../../../clusters/agent/index.md) instead of the certificate-based method can be tracked [in this GitLab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/299350) and [this GitLab Epic](https://gitlab.com/groups/gitlab-org/-/epics/7057). Container Network Security in GitLab provides basic firewall functionality by leveraging Cilium diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index 283e6c0b81c..340c9397e9c 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -192,11 +192,10 @@ violations but don't block any traffic. To set Cilium to Blocking mode, you must lines to the `applications/cilium/values.yaml` file in your cluster management project: ```yaml -config: - policyAuditMode: false +policyEnforcementMode: "always" monitor: - eventTypes: ["drop"] + eventTypes: ["drop", "policy-verdict"] ``` ### Traffic is not being allowed as expected diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 06fa18d80c9..ccf90a3d3dd 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -290,7 +290,7 @@ The example code is available: - As a [clonable repository](https://gitlab.com/gitlab-org/serverless/examples/serverless-framework-js). - In a version with [tests and secret variables](https://gitlab.com/gitlab-org/project-templates/serverless-framework/). -You can also use a [template](../../working_with_projects.md#project-templates) +You can also use a [template](../../working_with_projects.md#create-a-project) (based on the version with tests and secret variables) from within the GitLab UI (see the `Serverless Framework/JS` template). diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index f6598f8846b..265a60c6f2c 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -539,7 +539,7 @@ server that has Python 3 installed, and may not work on other operating systems or with other versions of Python. 1. Install Certbot by running the - [`certbot-auto` wrapper script](https://certbot.eff.org/docs/install.html#certbot-auto). + [`certbot-auto` wrapper script](https://eff-certbot.readthedocs.io/install.html#certbot-auto). On the command line of your server, run the following commands: ```shell diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index c138dc64d19..a95e4d2bc26 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -11,6 +11,10 @@ type: reference > - Code Owners for merge request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9. > - Moved to GitLab Premium in 13.9. +INFO: +Get access to Code Owners and more with a +[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-code-owners-docs). + Code Owners define who owns specific files or directories in a repository. - The users you define as Code Owners are displayed in the UI when you browse directories. @@ -173,12 +177,16 @@ entries under **Database**. The entries defined under the sections **Documentati ### Make a Code Owners section optional -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab Premium 13.8 behind a feature flag, enabled by default. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53227) in GitLab 13.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab Premium 13.8. -You can make a section optional, so that approval from the Code Owners in that section is optional. +You can designate optional sections in your Code Owners file. Prepend the +section name with the caret `^` character to treat the entire section as optional. +Optional sections enable you to designate responsible parties for various parts +of your codebase, but not require approval from them. This approach provides +a more relaxed policy for parts of your project that are frequently updated, +but don't require stringent reviews. -Put a caret `^` character before the Code Owners section name. For example: +In this example, the `[Go]` section is optional: ```plaintext [Documentation] @@ -200,8 +208,12 @@ If a section is duplicated in the file, and one of them is marked as optional an Optional sections in the `CODEOWNERS` file are treated as optional only when changes are submitted by using merge requests. If a change is submitted directly to the protected branch, approval from Code Owners is still required, even if the -section is marked as optional. [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297638) -to allow direct pushes to the protected branch for sections marked as optional. +section is marked as optional. + +### Allowed to Push + +The Code Owner approval and protected branch features do not apply to users who +are **Allowed to push**. ## Example `CODEOWNERS` file diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 5b19a54bd91..66e5931fa4c 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -71,7 +71,7 @@ To create the `.gitlab/issue_templates` directory: 1. Select **New directory**. 1. Name your directory `issue_templates` and commit to your default branch. -To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-a-new-issue) +To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-an-issue) and see if you can choose a description template. ## Create a merge request template diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index e1a81ae1bba..72bf0841687 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -52,9 +52,12 @@ self-managed GitLab instance. - If you're importing to a self-managed GitLab instance, you can alternatively use the [GitHub Rake task](../../../administration/raketasks/github_import.md) to import projects without the constraints of a [Sidekiq](../../../development/sidekiq_style_guide.md) worker. -- If you're importing from GitHub Enterprise to your self-managed GitLab instance, you must first enable - [GitHub integration](../../../integration/github.md). +- If you're importing from GitHub Enterprise to your self-managed GitLab instance: + - You must first enable [GitHub integration](../../../integration/github.md). - To import projects from GitHub Enterprise to GitLab.com, use the [Import API](../../../api/import.md). + - If GitLab is behind a HTTP/HTTPS proxy you must populate the [allowlist for local requests](../../../security/webhooks.md#allowlist-for-local-requests) + with `github.com` and `api.github.com` to solve the hostname. For more information, read the issue + [Importing a GitHub project requires DNS resolution even when behind a proxy](https://gitlab.com/gitlab-org/gitlab/-/issues/37941) - If you're importing from GitHub.com to your self-managed GitLab instance, setting up GitHub integration is not required. You can use the [Import API](../../../api/import.md). diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 6e02a9bf5ab..9d7ed593d41 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -76,7 +76,7 @@ a self-managed instance from an old server to a new server. The backups produced don't depend on the operating system running GitLab. You can therefore use the restore method to switch between different operating system distributions or versions, as long -as the same GitLab version [is available for installation](../../../administration/package_information/deprecated_os.md). +as the same GitLab version [is available for installation](../../../administration/package_information/supported_os.md). To instead merge two self-managed GitLab instances together, use the instructions in [Migrate from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom). diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 78cd2f8fb79..07e8ea1dc06 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -146,7 +146,7 @@ There are numerous [APIs](../../api/index.md) to use with your projects: - [Markdown](../../api/markdown.md) - [Merge Requests](../../api/merge_requests.md) - [Milestones](../../api/milestones.md) -- [Services](../../api/services.md) +- [Services](../../api/integrations.md) - [Snippets](../../api/project_snippets.md) - [Templates](../../api/project_templates.md) - [Traffic](../../api/project_statistics.md) diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 436df07d673..957290c5f20 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -149,7 +149,7 @@ Supported values are: | Name | Example | | ----- | ------- | | `bar` |  | -| `bar` (time series, i.e. when `group_by` is used) |  | +| `bar` (time series, that is when `group_by` is used) |  | | `line` |  | | `stacked-bar` |  | diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index 963fca34827..b4d7790df1d 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -37,7 +37,7 @@ Complete these steps in GitLab: 1. Select **Asana**. 1. Ensure that the **Active** toggle is enabled. 1. Paste the token you generated in Asana. -1. (Optional) To restrict this setting to specific branches, list them in the **Restrict to branch** +1. Optional. To restrict this setting to specific branches, list them in the **Restrict to branch** field, separated with commas. 1. Select **Save changes** or optionally select **Test settings**. diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 58cfd8c3a2f..38de8d9f1af 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -4,59 +4,66 @@ group: Integrations info: 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 Service **(FREE)** +# Atlassian Bamboo integration **(FREE)** -GitLab provides integration with Atlassian Bamboo for continuous integration. -When configured, pushes to a project trigger a build in Bamboo automatically. -Merge requests also display CI/CD status showing whether the build is pending, -failed, or completed successfully. It also provides a link to the Bamboo build -page for more information. +You can automatically trigger builds in Atlassian Bamboo when you push changes +to your project in GitLab. -Bamboo doesn't quite provide the same features as a traditional build system when -it comes to accepting webhooks and commit data. There are a few things that -need to be configured in a Bamboo build plan before GitLab can integrate. +When this integration is configured, merge requests also display the following information: -## Setup +- A CI/CD status that shows if the build is pending, failed, or has completed successfully. +- A link to the Bamboo build page for more information. -### Complete these steps in Bamboo +Bamboo doesn't provide the same features as a traditional build system when +accepting webhooks and commit data. You must configure a Bamboo +build plan before you configure the integration in GitLab. -1. Navigate to a Bamboo build plan and choose **Configure plan** from the **Actions** - dropdown. +## Configure Bamboo + +1. In Bamboo, go to a build plan and choose **Actions > Configure plan**. 1. Select the **Triggers** tab. -1. Click **Add trigger**. -1. Enter a description such as **GitLab trigger**. -1. Choose **Repository triggers the build when changes are committed**. +1. Select **Add trigger**. +1. Enter a description like `GitLab trigger`. +1. Select **Repository triggers the build when changes are committed**. 1. Select the checkbox for one or more repositories. -1. Enter the GitLab IP address in the **Trigger IP addresses** box. This is a - list of IP addresses that are allowed to trigger Bamboo builds. +1. Enter the GitLab IP address in **Trigger IP addresses**. These IP addresses + are allowed to trigger Bamboo builds. 1. Save the trigger. -1. In the left pane, select a build stage. If you have multiple build stages - you want to select the last stage that contains the Git checkout task. +1. In the left pane, select a build stage. If you have multiple build stages, + select the last stage that contains the Git checkout task. 1. Select the **Miscellaneous** tab. -1. Under **Pattern Match Labeling** put `${bamboo.repository.revision.number}` - in the **Labels** box. -1. Save - -Bamboo is now ready to accept triggers from GitLab. Next, set up the Bamboo -service in GitLab. - -### Complete these steps in GitLab - -1. Navigate to the project you want to configure to trigger builds. -1. Navigate to the [Integrations page](overview.md#accessing-integrations) -1. Click **Atlassian Bamboo**. -1. Ensure that the **Active** toggle is enabled. -1. Enter the base URL of your Bamboo server. `https://bamboo.example.com` -1. Enter the build key from your Bamboo build plan. Build keys are typically made - up from the Project Key and Plan Key that are set on project/plan creation and - separated with a dash (`-`), for example **PROJ-PLAN**. This is a short, all - uppercase identifier that is unique. When viewing a plan in Bamboo, the - build key is also shown in the browser URL, for example `https://bamboo.example.com/browse/PROJ-PLAN`. -1. If necessary, enter username and password for a Bamboo user that has +1. Under **Pattern Match Labeling** enter `${bamboo.repository.revision.number}` + in **Labels**. +1. Select **Save**. + +Bamboo is ready to accept triggers from GitLab. Next, set up the Bamboo +integration in GitLab. + +## Configure GitLab + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Atlassian Bamboo**. +1. Ensure the **Active** checkbox is selected. +1. Enter the base URL of your Bamboo server. For example, `https://bamboo.example.com`. +1. Enter the [build key](#identify-the-bamboo-build-plan-build-key) from your Bamboo + build plan. +1. If necessary, enter a username and password for a Bamboo user that has access to trigger the build plan. Leave these fields blank if you do not require authentication. -1. Save or optionally click **Test Settings**. **Test Settings** - actually triggers a build in Bamboo. +1. Optional. To test the configuration and trigger a build in Bamboo, + select **Test Settings**. +1. Select **Save changes**. + +### Identify the Bamboo build plan build key + +A build key is a unique identifier typically made up from the project key and +plan key. +Build keys are short, all uppercase, and separated with a dash (`-`), +for example `PROJ-PLAN`. + +The build key is included in the browser URL when you view a plan in +Bamboo. For example, `https://bamboo.example.com/browse/PROJ-PLAN`. ## Troubleshooting diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 47a81594ca9..9f1ea3796c6 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -6,17 +6,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitHub project integration **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3836) in GitLab Premium 10.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3836) in GitLab 10.6. -GitLab provides an integration for updating the pipeline statuses on GitHub. -This is especially useful if using GitLab for CI/CD only. - -This project integration is separate from the [instance wide GitHub integration](../import/github.md#mirror-a-repository-and-share-pipeline-status) -and is automatically configured on [GitHub import](../../../integration/github.md). +You can update GitHub with pipeline status updates from GitLab. +This integration can help you if you use GitLab for CI/CD.  -## Configuration +This project integration is separate from the [instance-wide GitHub integration](../import/github.md#mirror-a-repository-and-share-pipeline-status) +and is automatically configured when you import a [GitHub project](../../../integration/github.md). + +## Configure the integration This integration requires a [GitHub API token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `repo:status` access granted. @@ -26,31 +26,39 @@ Complete these steps on GitHub: 1. Go to your **Personal access tokens** page at <https://github.com/settings/tokens>. 1. Select **Generate new token**. 1. Under **Note**, enter a name for the new token. -1. Ensure that `repo:status` is checked and select **Generate token**. +1. Ensure `repo:status` is selected and select **Generate token**. 1. Copy the generated token to use in GitLab. Complete these steps in GitLab: -1. Go to the project you want to configure. -1. Go to the [Integrations page](overview.md#accessing-integrations) +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **GitHub**. -1. Ensure that the **Active** toggle is enabled. -1. Paste the token you generated on GitHub. -1. Enter the path to your project on GitHub, such as `https://github.com/username/repository`. -1. (Optional) To disable static status check names, clear the **Enable static status check names** checkbox. -1. Select **Save changes** or optionally select **Test settings**. +1. Ensure the **Active** checkbox is selected. +1. In **Token**, paste the token you generated on GitHub. +1. In **Repository URL**, enter the path to your project on GitHub, such as `https://github.com/username/repository`. +1. Optional. To disable [static status check names](#static-or-dynamic-status-check-names), clear the **Enable static status check names** checkbox. +1. Optional. Select **Test settings**. +1. Select **Save changes**. After configuring the integration, see [Pipelines for external pull requests](../../../ci/ci_cd_for_external_repos/#pipelines-for-external-pull-requests) to configure pipelines to run for open pull requests. ### Static or dynamic status check names -> - Introduced in GitLab 11.5: using static status check names as opt-in option. -> - [In GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/9931), static status check names is default behavior for new projects. +> - Introduced in GitLab 11.5 with static status check names as an opt-in option. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/9931) in GitLab 12.4 to make static status check names the default behavior for new projects. + +A status check name can be static or dynamic: + +- **Static**: The hostname of your + GitLab instance is appended to the status check name. -This makes it possible to mark these status checks as **Required** on GitHub. +- **Dynamic**: The branch name is appended + to the status check name. -When **Enable static status check names** is checked on the integration page, your -GitLab instance host name is appended to a status check name. +The **Enable static status check names** option enables you to configure +required status checks in GitHub, which need a consistent (static) name to work correctly. -When unchecked, it uses dynamic status check names and appends the branch name. +If you [disable this option](#configure-the-integration), +GitLab uses dynamic status check names instead. diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index bcaedbc4b10..7a96bb74e3f 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -32,7 +32,7 @@ Select a room and create a webhook: 1. Enter the room where you want to receive notifications from GitLab. 1. Open the room dropdown menu on the top-left and select **Manage webhooks**. 1. Enter the name for your webhook, for example "GitLab integration". -1. (Optional) Add an avatar for your bot. +1. Optional. Add an avatar for your bot. 1. Select **Save**. 1. Copy the webhook URL. @@ -46,7 +46,7 @@ Enable the Google Chat integration in GitLab: 1. Scroll down to the end of the page where you find a **Webhook** field. 1. Enter the webhook URL you copied from Google Chat. 1. Select the events you want to be notified about in your Google Chat room. -1. (Optional) Select **Test settings** to verify the connection. +1. Optional. Select **Test settings** to verify the connection. 1. Select **Save changes**. To test the integration, make a change based on the events you selected and diff --git a/doc/user/project/integrations/img/webhook_testing.png b/doc/user/project/integrations/img/webhook_testing.png Binary files differindex 27836556acc..88ce05668f9 100644 --- a/doc/user/project/integrations/img/webhook_testing.png +++ b/doc/user/project/integrations/img/webhook_testing.png diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index b96605ff5c9..279b139bacd 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -10,7 +10,7 @@ GitLab provides a way to push update messages to an irker server. When configured, pushes to a project trigger the service to send data directly to the irker server. -See also the [irker integration API documentation](../../../api/services.md). +See also the [irker integration API documentation](../../../api/integrations.md). For more information, see the [irker project homepage](https://gitlab.com/esr/irker). diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 119f219499c..f3f8d900e12 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -50,12 +50,12 @@ Then fill in the integration configuration: - **Webhook**: The incoming webhook URL on Mattermost, similar to `http://mattermost.example/hooks/5xo…`. -- **Username**: (Optional) The username shown in messages sent to Mattermost. +- **Username**: Optional. The username shown in messages sent to Mattermost. To change the bot's username, provide a value. - **Notify only broken pipelines**: If you enable the **Pipeline** event, and you want notifications about failed pipelines only. - **Branches for which notifications are to be sent**: The branches to send notifications for. -- **Labels to be notified**: (Optional) Labels required for the issue or merge request +- **Labels to be notified**: Optional. Labels required for the issue or merge request to trigger a notification. Leave blank to notify for all issues and merge requests. - **Labels to be notified behavior**: When you use the **Labels to be notified** filter, messages are sent when an issue or merge request contains _any_ of the labels specified diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index 93a3490e4b6..8b17f4afaa8 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -42,6 +42,6 @@ Complete these steps in GitLab: 1. Select **Pivotal Tracker**. 1. Ensure that the **Active** toggle is enabled. 1. Paste the token you generated in Pivotal Tracker. -1. (Optional) To restrict this setting to specific branches, list them in the **Restrict to branch** +1. Optional. To restrict this setting to specific branches, list them in the **Restrict to branch** field, separated with commas. 1. Select **Save changes** or optionally select **Test settings**. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index d399c7f2901..87f38c3482b 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -31,7 +31,7 @@ to control GitLab from Slack. Slash commands are configured separately. [Triggers for Slack notifications](#triggers-for-slack-notifications). By default, messages are sent to the channel you configured during [Slack configuration](#configure-slack). -1. (Optional) To send messages to a different channel, multiple channels, or as +1. Optional. To send messages to a different channel, multiple channels, or as a direct message: - *To send messages to channels,* enter the Slack channel names, separated by commas. @@ -42,7 +42,7 @@ to control GitLab from Slack. Slash commands are configured separately. 1. In **Webhook**, enter the webhook URL you copied in the [Slack configuration](#configure-slack) step. -1. (Optional) In **Username**, enter the username of the Slack bot that sends +1. Optional. In **Username**, enter the username of the Slack bot that sends the notifications. 1. Select the **Notify only broken pipelines** checkbox to notify only on failures. 1. In the **Branches for which notifications are to be sent** dropdown, select which types of branches diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 4c35f007fc7..47a2d215024 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -219,27 +219,6 @@ This ordering also affects [issue lists](issues/sorting_issue_lists.md). Changing the order in an issue board changes the ordering in an issue list, and vice versa. -### GraphQL-based issue boards - -<!-- This anchor is linked from #blocked-issues as well. --> - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. -> - [Deployed behind a feature flag](../feature_flags.md), enabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/248908) in GitLab 14.1 -> - [Feature flag `graphql_board_lists`](https://gitlab.com/gitlab-org/gitlab/-/issues/248908) removed in GitLab 14.3 - -There can be -[risks when disabling released features](../../administration/feature_flags.md#risks-when-disabling-released-features). -Refer to this feature's version history for more details. - -Using GraphQL-based boards gives you these -additional features: - -- [Edit more issue attributes](#edit-an-issue) -- [View blocked issues](#blocked-issues) - -Learn more about the known issues in [epic 5596](https://gitlab.com/groups/gitlab-org/-/epics/5596). - ## GitLab Enterprise features for issue boards GitLab issue boards are available on the GitLab Free tier, but some @@ -334,19 +313,13 @@ As in other list types, click the trash icon to remove a list. ### Iteration lists **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250479) in GitLab 13.11. -> - Enabled on GitLab.com and is ready for production use. -> - Enabled with `iteration_board_lists` flag for self-managed GitLab and is ready for production use. -> GitLab administrators can opt to [disable the feature flag](#enable-or-disable-iteration-lists-in-boards). - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, ask an -administrator to [disable the `iteration_board_lists` flag](../../administration/feature_flags.md). -On GitLab.com, this feature is available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250479) in GitLab 13.11 [with a flag](../../administration/feature_flags.md) named `iteration_board_lists`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75404) in GitLab 14.6. Feature flag `iteration_board_lists` removed. You're also able to create lists of an iteration. -These are lists that filter issues by the assigned -iteration. To add an iteration list: +These lists filter issues by the assigned iteration. + +To add an iteration list: 1. Select **Create list**. 1. Select **Iteration**. @@ -434,8 +407,6 @@ status. When you hover over the blocked icon (**{issue-block}**), a detailed information popover is displayed. -This feature is only supported when using the [GraphQL-based boards](#graphql-based-issue-boards). The feature is enabled by default regardless when you use group issue boards in epic swimlanes mode. -  ## Actions you can take on an issue board @@ -457,25 +428,25 @@ If you're not able to do some of the things above, make sure you have the right ### Edit an issue +> Editing title, iteration, and confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/248908) in GitLab 14.1. + You can edit an issue without leaving the board view. To open the right sidebar, select an issue card (not its title). You can edit the following issue attributes in the right sidebar: - Assignees -- [Epic](../group/epics/index.md) -- Milestone -- Time tracking value (view only) +- Confidentiality - Due date +- [Epic](../group/epics/index.md) +- [Iteration](../group/iterations/index.md) - Labels -- [Weight](issues/issue_weight.md) +- Milestone - Notifications setting - -When you use [GraphQL-based boards](#graphql-based-issue-boards), you can also edit the following issue attributes: - - Title -- [Iteration](../group/iterations/index.md) -- Confidentiality +- [Weight](issues/issue_weight.md) + +Additionally, you can also see the time tracking value. ### Create a new list @@ -620,13 +591,12 @@ and the target list. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. > - [Placed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61955) behind a [feature flag](../feature_flags.md), disabled by default in GitLab 14.0. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-multi-selecting-issue-cards). **(FREE SELF)** -This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). -Refer to this feature's version history for more details. +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an +administrator to [enable the feature flag](../../administration/feature_flags.md) named `board_multi_select`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. You can select multiple issue cards, then drag the group to another position within the list, or to another list. This makes it faster to reorder many issues at once. @@ -668,41 +638,3 @@ A few things to remember: - For performance and visibility reasons, each list shows the first 20 issues by default. If you have more than 20 issues, start scrolling down and the next 20 appear. - -### Enable or disable iteration lists in boards **(PREMIUM SELF)** - -The iteration list 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 disable it. - -To enable it: - -```ruby -Feature.enable(:iteration_board_lists) -``` - -To disable it: - -```ruby -Feature.disable(:iteration_board_lists) -``` - -### Enable or disable multi-selecting issue cards **(FREE SELF)** - -Multi-selecting issue cards is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:board_multi_select) -``` - -To disable it: - -```ruby -Feature.disable(:board_multi_select) -``` diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index b8a01f7ccd6..e8c58f2feb9 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -42,6 +42,11 @@ system note in the issue's comments.  +When an issue is made confidential, only users with at least the [Reporter role](../../permissions.md) +for the project have access to the issue. +Users with Guest or [Minimal](../../permissions.md#users-with-minimal-access) roles can't access +the issue even if they were actively participating before the change. + ## Indications of a confidential issue There are a few things that visually separate a confidential issue from a @@ -88,7 +93,7 @@ sees in the project's search results respectively. |:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------| |  |  | -## Related links +## Related topics - [Merge requests for confidential issues](../merge_requests/confidential.md) - [Make an epic confidential](../../group/epics/manage_epics.md#make-an-epic-confidential) diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 02a4f6a4384..69dc0cbafd8 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -10,7 +10,7 @@ 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`. Other columns are **not** imported. If you want to -retain columns such as labels and milestones, consider the [Move Issue feature](managing_issues.md#moving-issues). +retain columns such as labels and milestones, consider the [Move Issue feature](managing_issues.md#move-an-issue). The user uploading the CSV file is set as the author of the imported issues. @@ -48,7 +48,7 @@ When importing issues from a CSV file, it must be formatted in a certain way: - **double-quote character:** The double-quote (`"`) character is used to quote fields, enabling the use of the column separator within a field (see the third line in the sample CSV data below). To insert a double-quote (`"`) within a quoted - field, use two double-quote characters in succession, i.e. `""`. + field, use two double-quote characters in succession (`""`). - **data rows:** After the header row, succeeding rows must follow the same column order. The issue title is required while the description is optional. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 37c00bf0efa..ecf35fc4dcf 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -271,4 +271,4 @@ This is rendered as: User activity events on designs (creation, deletion, and updates) are tracked by GitLab and displayed on the [user profile](../../profile/index.md#access-your-user-profile), [group](../../group/index.md#view-group-activity), -and [project](../working_with_projects.md#project-activity) activity pages. +and [project](../working_with_projects.md#view-project-activity) activity pages. diff --git a/doc/user/project/issues/img/button_close_issue_v13_6.png b/doc/user/project/issues/img/button_close_issue_v13_6.png Binary files differdeleted file mode 100644 index 6c7f8da496b..00000000000 --- a/doc/user/project/issues/img/button_close_issue_v13_6.png +++ /dev/null diff --git a/doc/user/project/issues/img/comment-or-discussion.png b/doc/user/project/issues/img/comment-or-discussion.png Binary files differdeleted file mode 100644 index a29014c984c..00000000000 --- a/doc/user/project/issues/img/comment-or-discussion.png +++ /dev/null diff --git a/doc/user/project/issues/img/create_mr_from_issue.png b/doc/user/project/issues/img/create_mr_from_issue.png Binary files differdeleted file mode 100644 index d05a678cd17..00000000000 --- a/doc/user/project/issues/img/create_mr_from_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/delete_issue_v13_11.png b/doc/user/project/issues/img/delete_issue_v13_11.png Binary files differdeleted file mode 100644 index d9905012eab..00000000000 --- a/doc/user/project/issues/img/delete_issue_v13_11.png +++ /dev/null diff --git a/doc/user/project/issues/img/disable_issue_auto_close.png b/doc/user/project/issues/img/disable_issue_auto_close.png Binary files differdeleted file mode 100644 index 5894d39622a..00000000000 --- a/doc/user/project/issues/img/disable_issue_auto_close.png +++ /dev/null diff --git a/doc/user/project/issues/img/issue_activity_sort_order_v12_10.png b/doc/user/project/issues/img/issue_activity_sort_order_v12_10.png Binary files differdeleted file mode 100644 index 3e19ee1ac66..00000000000 --- a/doc/user/project/issues/img/issue_activity_sort_order_v12_10.png +++ /dev/null diff --git a/doc/user/project/issues/img/issue_type_change_v13_12.png b/doc/user/project/issues/img/issue_type_change_v13_12.png Binary files differdeleted file mode 100644 index 55aa607b878..00000000000 --- a/doc/user/project/issues/img/issue_type_change_v13_12.png +++ /dev/null diff --git a/doc/user/project/issues/img/issues_main_view_numbered.png b/doc/user/project/issues/img/issues_main_view_numbered.png Binary files differdeleted file mode 100644 index 92b9df44972..00000000000 --- a/doc/user/project/issues/img/issues_main_view_numbered.png +++ /dev/null diff --git a/doc/user/project/issues/img/merge_request_closes_issue_v13_11.png b/doc/user/project/issues/img/merge_request_closes_issue_v13_11.png Binary files differdeleted file mode 100644 index 26b42239c12..00000000000 --- a/doc/user/project/issues/img/merge_request_closes_issue_v13_11.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_from_email.png b/doc/user/project/issues/img/new_issue_from_email.png Binary files differdeleted file mode 100644 index 6da899ea37c..00000000000 --- a/doc/user/project/issues/img/new_issue_from_email.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_from_issue_board.png b/doc/user/project/issues/img/new_issue_from_issue_board.png Binary files differdeleted file mode 100644 index 30a1ffb9011..00000000000 --- a/doc/user/project/issues/img/new_issue_from_issue_board.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png b/doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png Binary files differdeleted file mode 100644 index 902aa40614a..00000000000 --- a/doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_from_projects_dashboard.png b/doc/user/project/issues/img/new_issue_from_projects_dashboard.png Binary files differdeleted file mode 100644 index 474ca2b45c0..00000000000 --- a/doc/user/project/issues/img/new_issue_from_projects_dashboard.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_from_tracker_list.png b/doc/user/project/issues/img/new_issue_from_tracker_list.png Binary files differdeleted file mode 100644 index 66793cb44fa..00000000000 --- a/doc/user/project/issues/img/new_issue_from_tracker_list.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_v13_1.png b/doc/user/project/issues/img/new_issue_v13_1.png Binary files differdeleted file mode 100644 index a66846c234e..00000000000 --- a/doc/user/project/issues/img/new_issue_v13_1.png +++ /dev/null diff --git a/doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png b/doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png Binary files differdeleted file mode 100644 index 4612ae254d4..00000000000 --- a/doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png +++ /dev/null diff --git a/doc/user/project/issues/img/show-all-activity.png b/doc/user/project/issues/img/show-all-activity.png Binary files differdeleted file mode 100644 index 55c6f5ab5db..00000000000 --- a/doc/user/project/issues/img/show-all-activity.png +++ /dev/null diff --git a/doc/user/project/issues/img/sidebar_move_issue.png b/doc/user/project/issues/img/sidebar_move_issue.png Binary files differdeleted file mode 100644 index 031284a24b2..00000000000 --- a/doc/user/project/issues/img/sidebar_move_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/similar_issues.png b/doc/user/project/issues/img/similar_issues.png Binary files differdeleted file mode 100644 index c5b7902b2ac..00000000000 --- a/doc/user/project/issues/img/similar_issues.png +++ /dev/null diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 64838b261ce..bd0cf92e320 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -29,24 +29,25 @@ To learn how the GitLab Strategic Marketing department uses GitLab issues with [ ## Related topics -- [Create issues](managing_issues.md#create-a-new-issue) +- [Create issues](managing_issues.md#create-an-issue) - [Create an issue from a template](../../project/description_templates.md#use-the-templates) -- [Move issues](managing_issues.md#moving-issues) -- [Close issues](managing_issues.md#closing-issues) -- [Delete issues](managing_issues.md#deleting-issues) +- [Edit issues](managing_issues.md#edit-an-issue) +- [Move issues](managing_issues.md#move-an-issue) +- [Close issues](managing_issues.md#close-an-issue) +- [Delete issues](managing_issues.md#delete-an-issue) - [Promote issues](managing_issues.md#promote-an-issue-to-an-epic) - [Set a due date](due_dates.md) - [Import issues](csv_import.md) - [Export issues](csv_export.md) - [Upload designs to issues](design_management.md) - [Linked issues](related_issues.md) +- [Similar issues](managing_issues.md#similar-issues) +- [Health status](managing_issues.md#health-status) - [Cross-link issues](crosslinking_issues.md) -- [Bulk edit issues](../issues/managing_issues.md) - [Sort issue lists](sorting_issue_lists.md) - [Search for issues](../../search/index.md#filter-issue-and-merge-request-lists) - [Epics](../../group/epics/index.md) - [Issue boards](../issue_board.md) - [Issues API](../../../api/issues.md) - [Configure an external issue tracker](../../../integration/external-issue-tracker.md) -- [Parts of an issue](issue_data_and_actions.md) - [Tasks](../../tasks.md) diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 6bb60e5e31a..66ca29c094e 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -1,315 +1,9 @@ --- -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/#assignments +redirect_to: 'index.md' +remove_date: '2022-02-24' --- -# Issue Data and Actions **(FREE)** +This file was moved to [another location](index.md). -Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. - -## Parts of an 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 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) - - **3.1.** [Multiple Assignees](#multiple-assignees) -- **4.** [Epic](#epic) -- **5.** [Milestone](#milestone) -- **6.** [Time tracking](#time-tracking) -- **7.** [Due date](#due-date) -- **8.** [Labels](#labels) -- **9.** [Weight](#weight) -- **10.** [Confidentiality](#confidentiality) -- **11.** [Lock issue](#lock-issue) -- **12.** [Participants](#participants) -- **13.** [Notifications](#notifications) -- **14.** [Reference](#reference) -- [Issue email](#email) -- **15.** [Edit](#edit) -- **16.** [Description](#description) -- **17.** [Mentions](#mentions) -- **18.** [Linked Issues](#linked-issues) -- **19.** [Related Merge Requests](#related-merge-requests) -- **20.** [Award emoji](#award-emoji) -- **21.** [Show all activity](#show-all-activity) -- **22.** [Create Merge Request](#create-merge-request) -- **23.** [Issue history](#issue-history) - - [Activity sort order](#activity-sort-order) -- **24.** [Comments](#comments) -- **25.** [Submit comment, start a thread, or comment and close](#submit-comment-start-a-thread-or-comment-and-close) -- **26.** [Zoom meetings](#zoom-meetings) - -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. - -### Issue actions - -In an open issue, you can close it by selecting the **Close issue** button. -The issue is marked as closed but is not deleted. - -To reopen a closed issue, select the **Reopen issue** button. -A reopened issue is no different from any other open issue. - -To access additional actions, select the vertical ellipsis -(**{ellipsis_v}**) button: - -- To create a new issue in the same project, select **New issue** in the dropdown menu. - -- If you are not the issue author, you can [submit an abuse report](../../report_abuse.md). - Select **Report abuse** in the dropdown menu. - -### To Do - -You can add issues to and remove issues from your [GitLab To-Do List](../../todos.md). - -The button to do this has a different label depending on whether the issue is already on your To-Do -List or not. If the issue is: - -- Already on your To-Do List: The button is labeled **Mark as done**. Click the button to remove the issue from your To-Do List. -- Not on your To-Do List: The button is labeled **Add a to do**. Click the button to add the issue to your To-Do List. - -### Assignee - -An issue can be assigned to: - -- Yourself. -- Another person. -- [Many people](#multiple-assignees). **(PREMIUM)** - -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 appears in their assigned issues list. - -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 **(PREMIUM)** - -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. - -To help with this, you can use GitLab to -[assign multiple people](multiple_assignees_for_issues.md) to an issue. - -### Epic **(PREMIUM)** - -You can assign issues to an [Epic](../../group/epics/index.md), which allows better -management of groups of related issues. - -### Milestone - -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 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 - -When you work on a tight schedule, it's important to have a way to set a deadline for -implementations and for solving problems. This can be done in the [due date](due_dates.md) -element. Due dates can be changed as many times as needed. - -### Labels - -Categorize issues by giving them [labels](../labels.md). They help to organize workflows, -and they enable you to work with the [issue board](../issue_board.md). - -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. - -If a label doesn't exist yet, you can create one by clicking **Edit** -followed by **Create new label** in the dropdown menu. - -### Weight **(PREMIUM)** - -[Assign a weight](issue_weight.md) to an issue. -Larger values are used to indicate more effort is required to complete the issue. Only -positive values or zero are allowed. - -### Confidentiality - -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 - -You can [lock the issue](../../discussions/index.md#prevent-comments-by-locking-an-issue) -to prevent further comments from being added. - -### Participants - -All the users involved in that issue. Either they participated in the [thread](../../discussions/index.md), -or were mentioned in the description or threads. - -### Notifications - -Select the toggle to enable or disable [notifications](../../profile/notifications.md#notifications-on-issues-merge-requests-and-epics) -for the issue. Notifications are automatically enabled after you participate in the issue in any way. - -### Reference - -- A quick "copy" button for that issue's reference, which looks like - `foo/bar#xxx`, where `foo` is the `username` or `groupname`, `bar` is the - `project-name`, and `xxx` is the issue number. - -### Email - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18816) in GitLab 13.8. - -Guest users can see a button in the right sidebar to copy the email address for the issue. -Sending an email to this address creates a comment containing the email body. - -### Edit - -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 - -The plain text title and description of the issue fill the top center of the issue page. -The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown), -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). **(PREMIUM)** - -### Mentions - -You can mention a user or a group present in your GitLab instance with `@username` or -`@groupname`. All mentioned users are notified via to-do items and emails, -unless they have disabled all [notifications](#notifications) in their user settings. -This is controlled in the [notification settings](../../profile/notifications.md). - -Mentions for yourself (the user currently signed in) are highlighted -in a different color, which allows you to quickly see which comments involve you. - -Avoid mentioning `@all` in issues and merge requests, as it sends an email notification -to all the members of that project's group. This might be interpreted as spam. - -### Linked Issues - -Issues that were mentioned as [linked issues](related_issues.md) are listed here. -You can also click the `+` to add more linked issues. - -### Related Merge Requests - -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 is also listed here. - -### Award 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#emojis). - -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 notifying them. - -### Show all activity - -You can filter what is displayed in the issue history by clicking on **Show all activity** -and selecting either: - -- **Show comments only**, which only shows threads and hides updates to the issue. -- **Show history only**, which hides threads and only shows updates. - -Also: - -- You can mention a user or a group present in your GitLab instance with - `@username` or `@groupname` and they are notified via to-do items - and emails, unless they have disabled all [notifications](#notifications) - in their user settings. -- 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/drafts.md) -in one action. The branch is named `issuenumber-title` by default, but you can -choose any name, and GitLab verifies that it is not already in use. The merge request -inherits the milestone and labels of the issue, and is set to automatically -close the issue when it is merged. - - - -Optionally, you can choose to create a [new branch](../repository/web_editor.md#create-a-new-branch-from-an-issue) -only, named after that issue. - -### Issue history - -All comments and updates to the issue are tracked and listed here, but this can be -filtered, as shown above. - -#### Activity sort order - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14588) in GitLab 12.10. - -You can reverse the default order and interact with the activity feed sorted by most recent items -at the top. Your preference is saved via local storage and automatically applied to every issue -you view. - -To change the activity sort order, click the **Oldest first** dropdown menu and select either oldest -or newest items to be shown first. - - - -### Comments - -Collaborate in the issue by posting comments in its thread. This text field also fully -supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). - -### Submit comment, start a thread, or comment and close - -After you write a comment, you can: - -- Click **Comment** to publish your comment. -- Choose **Start thread** from the dropdown list and start a new [thread](../../discussions/index.md#create-a-thread-without-replying-to-a-comment) - 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. - - - -You can also close the issue from here, so you don't need to scroll to the top of the issue page. - -### Zoom meetings - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31103) in GitLab 12.3. - -You can attach and remove Zoom meetings to issues using the `/zoom` and `/remove_zoom` [quick actions](../quick_actions.md) as part of -[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). - -Attaching a [Zoom](https://zoom.us) call an issue -results in a **Join Zoom meeting** button at the top of the issue, just under the header. - -Read more how to [add or remove a zoom meeting](associate_zoom_meeting.md). - -### Publish an issue **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. - -If a status page application is associated with the project, you can use the `/publish` [quick action](../quick_actions.md) to publish the issue. Refer to [GitLab Status Page](../../../operations/incident_management/status_page.md) for more information. +<!-- This redirect file can be deleted after <2022-02-24>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 6b3d5d6563a..1a23902514a 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -4,293 +4,411 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Managing issues **(FREE)** +# Manage issues **(FREE)** [GitLab Issues](index.md) are the fundamental medium for collaborating on ideas and planning work in GitLab. -Key actions for issues include: +## Create an issue -- [Creating issues](#create-a-new-issue) -- [Moving issues](#moving-issues) -- [Closing issues](#closing-issues) -- [Deleting issues](#deleting-issues) -- [Promoting issues](#promote-an-issue-to-an-epic) **(PREMIUM)** +When you create an issue, you are prompted to enter the fields of the issue. +If you know the values you want to assign to an issue, you can use +[quick actions](../quick_actions.md) to enter them. -## Create a new issue +You can create an issue in many ways in GitLab: -When you create a new issue, you are prompted to fill in the [data and fields of the issue](issue_data_and_actions.md), -as illustrated below. If you know the values you want to assign to an issue, you can use the -[Quick actions](../quick_actions.md) feature to input values. +- [From a project](#from-a-project) +- [From a group](#from-a-group) +- [From another issue](#from-another-issue) +- [From an issue board](#from-an-issue-board) +- [By sending an email](#by-sending-an-email) +- Using a URL with prefilled fields +- [Using Service Desk](#using-service-desk) -While creating an issue, you can associate it to an existing epic from current group by -selecting it using **Epic** dropdown. +### From a project -### Accessing the New Issue form +Prerequisites: -There are many ways to get to the New Issue form from a project's page: +- You must have at least the [Guest role](../../permissions.md) for the project. -- Navigate to your **Project's Dashboard** > **Issues** > **New Issue**: +To create an issue: -  +1. On the top bar, select **Menu > Projects** and find your project. +1. Either: -- From an **open issue** in your project, click the vertical ellipsis (**{ellipsis_v}**) button - to open a dropdown menu, and then click **New Issue** to create a new issue in the same project: + - On the left sidebar, select **Issues**, and then, in the top right corner, select **New issue**. + - On the top bar, select the plus sign (**{plus-square}**) and then, under **This project**, + select **New issue**. -  +1. Complete the [fields](#fields-in-the-new-issue-form). +1. Select **Create issue**. -- From your **Project's Dashboard**, click the plus sign (**+**) to open a dropdown - menu with a few options. Select **New Issue** to create an issue in that project: +The newly created issue opens. -  +### From a group -- From an **issue board**, create a new issue by clicking on the plus sign (**+**) at the top of a list. - It opens a new issue for that project, pre-labeled with its respective list. +Issues belong to projects, but when you're in a group, you can access and create issues that belong +to the projects in the group. -  +Prerequisites: -### Elements of the New Issue form +- You must have at least the [Guest role](../../permissions.md) for the project in the group. -> Ability to add the new issue to an epic [was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13847) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1. +To create an issue from a group: - +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Issues**. +1. In the top right corner, select **Select project to create issue**. +1. Select the project you'd like to create an issue for. The button now reflects the selected + project. +1. Select **New issue in `<project name>`**. +1. Complete the [fields](#fields-in-the-new-issue-form). +1. Select **Create issue**. -When you're creating a new issue, these are the fields you can fill in: +The newly created issue opens. -- Title -- Description -- Checkbox to make the issue [confidential](confidential_issues.md) -- Assignee -- Weight -- [Epic](../../group/epics/index.md) -- Due date -- Milestone -- Labels +The project you selected most recently becomes the default for your next visit. +This can save you a lot of time and clicks, if you mostly create issues for the same project. -### New issue from the group-level issue tracker +### From another issue -To visit the issue tracker for all projects in your group: +> New issue becoming linked to the issue of origin [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68226) in GitLab 14.3. -1. Go to the group dashboard. -1. On the left sidebar, select **Issues**. -1. In the top-right, select the **Select project to create issue** button. -1. Select the project you'd like to create an issue for. The button now reflects the selected - project. -1. Select the button to create an issue in the selected project. +You can create a new issue from an existing one. The two issues can then be marked as related. - +Prerequisites: -The project you selected most recently becomes the default for your next visit. -This should save you a lot of time and clicks, if you mostly create issues for the same project. +- You must have at least the [Guest role](../../permissions.md) for the project. -### New issue via Service Desk +To create an issue from another issue: -Enable [Service Desk](../service_desk.md) for your project and offer email support. -Now, when your customer sends a new email, a new issue can be created in -the appropriate project and followed up from there. +1. In an existing issue, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **New issue**. +1. Complete the [fields](#fields-in-the-new-issue-form). + The new issue's description is prefilled with `Related to #123`, where `123` is the ID of the + issue of origin. If you keep this mention in the description, the two issues become + [linked](related_issues.md). +1. Select **Create issue**. -### New issue via email +The newly created issue opens. -A link to **Email a new issue to this project** is displayed at the bottom of a project's -**Issues List** page. The link is shown only if your GitLab instance has [incoming email](../../../administration/incoming_email.md) -configured and there is at least one issue in the issue list. +### From an issue board - +You can create a new issue from an [issue board](../issue_board.md). -When you click this link, an email address is generated and displayed, which should be used -by **you only**, to create issues in this project. You can save this address as a -contact in your email client for quick access. +Prerequisites: -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 want to regenerate it, -click **Email a new issue to this project**, followed by **reset it**. +- You must have at least the [Guest role](../../permissions.md) for the project. + +To create an issue from a project issue board: + +1. On the top bar, select **Menu > Projects** and find your project. +1. Select **Issues > Boards**. +1. At the top of a board list, select **New issue** (**{plus-square}**). +1. Enter the issue's title. +1. Select **Create issue**. + +To create an issue from a group issue board: + +1. On the top bar, select **Menu > Groups** and find your group. +1. Select **Issues > Boards**. +1. At the top of a board list, select **New issue** (**{plus-square}**). +1. Enter the issue's title. +1. Under **Projects**, select the project in the group that the issue should belong to. +1. Select **Create issue**. -Sending an email to this address creates a new issue associated with your account for -this project, where: +The issue is created and shows up in the board list. It shares the list's characteristic, so, for +example, if the list is scoped to a label `Frontend`, the new issue also has this label. -- The email subject becomes the issue title. -- The email body becomes the issue description. -- [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported. +### By sending an email -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. +> Generated email address format changed in GitLab 11.7. +> The older format is still supported, so existing aliases and contacts still work. -### New issue via URL with prefilled fields +You can send an email to create an issue in a project on the project's +**Issues List** page. + +Prerequisites: + +- Your GitLab instance must have [incoming email](../../../administration/incoming_email.md) + configured. +- There must be at least one issue in the issue list. +- You must have at least the [Guest role](../../permissions.md) for the project. + +To email an issue to a project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. Select **Issues**. +1. At the bottom of the page, select **Email a new issue to this project**. +1. To copy the email address, select **Copy** (**{copy-to-clipboard}**). +1. From your email client, send an email to this address. + The subject is used as the title of the new issue, and the email body becomes the description. + You can use [Markdown](../../markdown.md) and [quick actions](../quick_actions.md). + +A new issue is created, with your user as the author. +You can save this address as a contact in your email client to use it again. + +WARNING: +The email address you see is a private email address, generated just for you. +**Keep it to yourself**, because anyone who knows it can create issues or merge requests as if they +were you. + +To regenerate the email address: + +1. On the issues list, select **Email a new issue to this project**. +1. Select **reset this token**. + +### Using a URL with prefilled values To link directly to the new issue page with prefilled fields, use query string parameters in a URL. You can embed a URL in an external -HTML page to create issues with certain -fields prefilled. +HTML page to create issues with certain fields prefilled. + +| Field | URL parameter | Notes | +| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| Title | `issue[title]` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Issue type | `issue[issue_type]` | Either `incident` or `issue`. | +| Description template | `issuable_template` | Cannot be used at the same time as `issue[description]`. Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Description | `issue[description]` | Cannot be used at the same time as `issuable_template`. Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Confidential | `issue[confidential]` | If `true`, the issue is marked as confidential. | + +Adapt these examples to form your new issue URL with prefilled fields. +To create an issue in the GitLab project: + +- With a prefilled title and description: + + ```plaintext + https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Whoa%2C%20we%27re%20half-way%20there&issue[description]=Whoa%2C%20livin%27%20in%20a%20URL + ``` -| Field | URL Parameter Name | Notes | -|----------------------|-----------------------|-------------------------------------------------------| -| title | `issue[title]` | | -| description | `issue[description]` | Cannot be used at the same time as `issuable_template`. | -| description template | `issuable_template` | Cannot be used at the same time as `issue[description]`. | -| issue type | `issue[issue_type]` | Either `incident` or `issue`. | -| confidential | `issue[confidential]` | Parameter value must be `true` to set to confidential. | +- With a prefilled title and description template: -Follow these examples to form your new issue URL with prefilled fields. + ```plaintext + https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Feature%20Proposal%20-%20basic + ``` -- For a new issue in the GitLab Community Edition project with a pre-filled title - and a pre-filled description, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea` -- For a new issue in the GitLab Community Edition project with a pre-filled title - and a pre-filled description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal` -- For a new issue in the GitLab Community Edition project with a pre-filled title, - a pre-filled description, and the confidential flag set, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true` +- With a prefilled title, description, and marked as confidential: -## Bulk edit issues at the project level + ```plaintext + https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true + ``` -> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. +### Using Service Desk + +To offer email support, enable [Service Desk](../service_desk.md) for your project. + +Now, when your customer sends a new email, a new issue can be created in +the appropriate project and followed up from there. + +### Fields in the new issue form + +> Adding the new issue to an epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13847) in GitLab 13.1. + +When you're creating a new issue, you can complete the following fields: + +- Title +- Type: either issue (default) or incident +- [Description template](../description_templates.md): overwrites anything in the Description text box +- Description: you can use [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) +- Checkbox to make the issue [confidential](confidential_issues.md) +- [Assignees](#assignee) +- [Weight](issue_weight.md) +- [Epic](../../group/epics/index.md) +- [Due date](due_dates.md) +- [Milestone](../milestones/index.md) +- [Labels](../labels.md) + +## Edit an issue + +You can edit an issue's title and description. + +Prerequisites: + +- You must have at least the [Reporter role](../../permissions.md) for the project. + +To edit an issue: + +1. To the right of the title, select **Edit title and description** (**{pencil}**). +1. Edit the available fields. +1. Select **Save changes**. + +### Bulk edit issues from a project + +> - Assigning epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. > - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. > - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. -Users with permission level of [Reporter or higher](../../permissions.md) can manage issues. +You can edit multiple issues at a time when you're in a project. + +Prerequisites: + +- You must have at least the [Reporter role](../../permissions.md) for the project. + +To edit multiple issues at the same time: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Issues**. +1. Select **Edit issues**. A sidebar on the right of your screen appears. +1. Select the checkboxes next to each issue you want to edit. +1. From the sidebar, edit the available fields. +1. Select **Update all**. When bulk editing issues in a project, you can edit the following attributes: -- Status (open/closed) -- Assignee +- Status (open or closed) +- [Assignees](#assignee) - [Epic](../../group/epics/index.md) - [Milestone](../milestones/index.md) - [Labels](../labels.md) - [Health status](#health-status) -- Notification subscription +- [Notification](../../profile/notifications.md) subscription - [Iteration](../../group/iterations/index.md) -To update multiple project issues at the same time: - -1. In a project, go to **Issues > List**. -1. Click **Edit issues**. A sidebar on the right-hand side of your screen appears with editable fields. -1. Select the checkboxes next to each issue you want to edit. -1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. - -## Bulk edit issues at the group level +### Bulk edit issues from a group > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in GitLab 12.1. -> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. +> - Assigning epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. > - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. > - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. -Users with permission level of [Reporter or higher](../../permissions.md) can manage issues. +You can edit multiple issues across multiple projects when you're in a group. + +Prerequisites: + +- You must have at least the [Reporter role](../../permissions.md) for a group. + +To edit multiple issues at the same time: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Issues**. +1. Select **Edit issues**. A sidebar on the right of your screen appears. +1. Select the checkboxes next to each issue you want to edit. +1. From the sidebar, edit the available fields. +1. Select **Update all**. When bulk editing issues in a group, you can edit the following attributes: - [Epic](../../group/epics/index.md) - [Milestone](../milestones/index.md) +- [Iteration](../../group/iterations/index.md) - [Labels](../labels.md) - [Health status](#health-status) -- [Iteration](../../group/iterations/index.md) -To update multiple project issues at the same time: +## Move an issue -1. In a group, go to **Issues > List**. -1. Click **Edit issues**. A sidebar on the right-hand side of your screen appears with editable fields. -1. Select the checkboxes next to each issue you want to edit. -1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. - -## Moving issues - -Moving an issue copies it to the target project, and closes it in the originating project. +When you move an issue, it's closed and copied to the target project. The original issue is not deleted. A system note, which indicates where it came from and went to, is added to both issues. -The "Move issue" button is at the bottom of the right-sidebar when viewing the issue. +Prerequisites: - +- You must have at least the [Reporter role](../../permissions.md) for the project. -### Moving issues in bulk **(FREE SELF)** +To move an issue: -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 moves all issues -that are not in status **closed** from one project to another. +1. Go to the issue. +1. On the right sidebar, select **Move issue**. +1. Search for a project to move the issue to. +1. Select **Move**. -To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below -script. Please be sure to change `project`, `admin_user`, and `target_project` to your values. -We do also recommend [creating a backup](../../../raketasks/backup_restore.md) before -attempting any changes in the console. +### Bulk move issues **(FREE SELF)** -```ruby -project = Project.find_by_full_path('full path of the project where issues are moved from') -issues = project.issues -admin_user = User.find_by_username('username of admin user') # make sure user has permissions to move the issues -target_project = Project.find_by_full_path('full path of target project where issues moved to') +You can move all open issues from one project to another. -issues.each do |issue| - if issue.state != "closed" && issue.moved_to.nil? - Issues::MoveService.new(project, admin_user).execute(issue, target_project) - else - puts "issue with id: #{issue.id} and title: #{issue.title} was not moved" - end -end; nil -``` +Prerequisites: + +- You must have at least the [Reporter role](../../permissions.md) for the project. + +To do it: + +1. Optional (but recommended). [Create a backup](../../../raketasks/backup_restore.md) before + attempting any changes in the console. +1. Open the [Rails console](../../../administration/operations/rails_console.md). +1. Run the following script. Make sure to change `project`, `admin_user`, and `target_project` to + your values. + + ```ruby + project = Project.find_by_full_path('full path of the project where issues are moved from') + issues = project.issues + admin_user = User.find_by_username('username of admin user') # make sure user has permissions to move the issues + target_project = Project.find_by_full_path('full path of target project where issues moved to') + + issues.each do |issue| + if issue.state != "closed" && issue.moved_to.nil? + Issues::MoveService.new(project, admin_user).execute(issue, target_project) + else + puts "issue with id: #{issue.id} and title: #{issue.title} was not moved" + end + end; nil + ``` + +1. To exit the Rails console, enter `quit`. -## Closing issues +## Close an issue -When you decide that an issue is resolved, or no longer needed, you can close the issue -using the close button: +When you decide that an issue is resolved or no longer needed, you can close it. +The issue is marked as closed but is not deleted. - +Prerequisites: -You can also close an issue from the [issue boards](../issue_board.md) by dragging an issue card -from its list and dropping it into the **Closed** list. +- You must have at least the [Reporter role](../../permissions.md) for the project. - +To close an issue, you can do the following: + +- At the top of the issue, select **Close issue**. +- In an [issue board](../issue_board.md), drag an issue card from its list into the **Closed** list. + +  + +### Reopen a closed issue + +Prerequisites: + +- You must have at least the [Reporter role](../../permissions.md) for the project. + +To reopen a closed issue, at the top of the issue, select **Reopen issue**. +A reopened issue is no different from any other open issue. ### Closing issues automatically -When a commit or merge request resolves issues, the issues -can be closed automatically when the commit reaches the project's default branch. +You can close issues automatically by using certain words in the commit message or MR description. -If a commit message or merge request description contains text matching a [defined pattern](#default-closing-pattern), -all issues referenced in the matched text are closed. This happens when the commit -is pushed to a project's [**default** branch](../repository/branches/default.md), -or when a commit or merge request is merged into it. +If a commit message or merge request description contains text matching the [defined pattern](#default-closing-pattern), +all issues referenced in the matched text are closed when either: -For example, if `Closes #4, #6, Related to #5` is included in a Merge Request -description, issues `#4` and `#6` are closed automatically when the MR is merged, but not `#5`. -Using `Related to` flags `#5` as a [related issue](related_issues.md), -but is not closed automatically. +- The commit is pushed to a project's [**default** branch](../repository/branches/default.md). +- The commit or merge request is merged into the default branch. - +For example, if you include `Closes #4, #6, Related to #5` in a merge request +description: -If the issue is in a different repository than the MR, add the full URL for the issue(s): +- Issues `#4` and `#6` are closed automatically when the MR is merged. +- Issue `#5` is marked as a [related issue](related_issues.md), but it's not closed automatically. -```markdown -Closes #4, #6, and https://gitlab.com/<username>/<projectname>/issues/<xxx> -``` +Alternatively, when you [create a merge request from an issue](../merge_requests/getting_started.md#merge-requests-to-close-issues), +it inherits the issue's milestone and labels. For performance reasons, automatic issue closing is disabled for the very first push from an existing repository. #### Default closing pattern -When not specified, this default issue closing pattern is used: +To automatically close an issue, use the following keywords followed by the issue reference. -```shell -\b((?:[Cc]los(?:e[sd]?|ing)|\b[Ff]ix(?:e[sd]|ing)?|\b[Rr]esolv(?:e[sd]?|ing)|\b[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?: *,? +and +| *,? *)?)|([A-Z][A-Z0-9_]+-\d+))+) -``` - -This translates to the following keywords: +Available keywords: - Close, Closes, Closed, Closing, close, closes, closed, closing - Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing - 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 the GitLab -source code that can match references to: +Available issue reference formats: - A local issue (`#123`). - A cross-project issue (`group/project#123`). -- A link to an issue (`https://gitlab.example.com/group/project/issues/123`). +- The full URL of an issue (`https://gitlab.example.com/group/project/issues/123`). -For example the following commit message: +For example: ```plaintext Awesome commit message @@ -300,54 +418,93 @@ This commit is also related to #17 and fixes #18, #19 and https://gitlab.example.com/group/otherproject/issues/23. ``` -closes `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, +The previous commit message closes `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, as well as `#22` and `#23` in `group/otherproject`. `#17` is not closed as it does -not match the pattern. It works with multi-line commit messages as well as one-liners -when used from the command line with `git commit -m`. +not match the pattern. + +You can use the closing patterns in multi-line commit messages or one-liners +done from the command line with `git commit -m`. -#### Disabling automatic issue closing +The default issue closing pattern regex: + +```shell +\b((?:[Cc]los(?:e[sd]?|ing)|\b[Ff]ix(?:e[sd]|ing)?|\b[Rr]esolv(?:e[sd]?|ing)|\b[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?: *,? +and +| *,? *)?)|([A-Z][A-Z0-9_]+-\d+))+) +``` + +#### Disable automatic issue closing > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19754) in GitLab 12.7. -The automatic issue closing feature can be disabled on a per-project basis -in the [project's repository settings](../settings/index.md). Referenced -issues are still displayed, but are not closed automatically. +You can disable the automatic issue closing feature on a per-project basis +in the [project's settings](../settings/index.md). + +Prerequisites: - +- You must have at least the [Maintainer role](../../permissions.md) for the project. -The automatic issue closing is also disabled in a project if the project has the issue tracker +To disable automatic issue closing: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Default branch**. +1. Select **Auto-close referenced issues on default branch**. +1. Select **Save changes**. + +Referenced issues are still displayed, but are not closed automatically. + +The automatic issue closing is disabled by default in a project if the project has the issue tracker disabled. If you want to enable automatic issue closing, make sure to [enable GitLab Issues](../settings/index.md#sharing-and-permissions). -This only applies to issues affected by new merge requests or commits. Already -closed issues remain as-is. +Changing this setting applies only to new merge requests or commits. Already +closed issues remain as they are. If issue tracking is enabled, disabling automatic issue closing only applies to merge requests -attempting to automatically close issues within the same project. +attempting to automatically close issues in the same project. Merge requests in other projects can still close another project's issues. -#### Customizing the issue closing pattern **(FREE SELF)** +#### Customize the issue closing pattern **(FREE SELF)** + +Prerequisites: -In order to change the default issue closing pattern, GitLab administrators must edit the +- You must have the [administrator access level](../../../administration/index.md) for your GitLab instance. + +To change the default issue closing pattern, edit the [`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md) of your installation. ## Change the issue type -Users with the [Developer role](../../permissions.md) -can change an issue's type. To do this, edit the issue and select an issue type from the -**Issue type** selector menu: +Prerequisites: + +- You must be the issue author or have at least the [Reporter role](../../permissions.md) for the project. + +To change issue type: + +1. To the right of the title, select **Edit title and description** (**{pencil}**). +1. Edit the issue and select an issue type from the **Issue type** dropdown list: -- [Issue](index.md) -- [Incident](../../../operations/incident_management/index.md) + - Issue + - [Incident](../../../operations/incident_management/index.md) - +1. Select **Save changes**. -## Deleting issues +## Delete an issue -Users with the [Owner role](../../permissions.md) can delete an issue by -editing it and selecting **Delete issue**. +> Deleting from the vertical ellipsis menu [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299933) in GitLab 14.6. - +Prerequisites: + +- You must have the [Owner role](../../permissions.md) for a project. + +To delete an issue: + +1. In an issue, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **Delete issue**. + +Alternatively: + +1. In an issue, select **Edit title and description** (**{pencil}**). +1. Select **Delete issue**. ## Promote an issue to an epic **(PREMIUM)** @@ -355,16 +512,16 @@ editing it and selecting **Delete issue**. > - Moved to GitLab Premium in 12.8. > - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in GitLab Premium 13.6. -You can promote an issue to an epic in the immediate parent group. +You can promote an issue to an [epic](../../group/epics/index.md) in the immediate parent group. To promote an issue to an epic: -1. In an issue, select the vertical ellipsis (**{ellipsis_v}**) button. +1. In an issue, select the vertical ellipsis (**{ellipsis_v}**). 1. Select **Promote to epic**. Alternatively, you can use the `/promote` [quick action](../quick_actions.md#issues-merge-requests-and-epics). -Read more about promoting an issue to an epic on the [Manage epics page](../../group/epics/manage_epics.md#promote-an-issue-to-an-epic). +Read more about [promoting an issues to epics](../../group/epics/manage_epics.md#promote-an-issue-to-an-epic). ## Add an issue to an iteration **(PREMIUM)** @@ -373,12 +530,41 @@ Read more about promoting an issue to an epic on the [Manage epics page](../../g To add an issue to an [iteration](../../group/iterations/index.md): -1. In an issue sidebar, click **Edit** next to **Iteration**. A dropdown appears. -1. Click an iteration you'd like to associate this issue with. +1. Go to the issue. +1. On the right sidebar, in the **Iteration** section, select **Edit**. +1. From the dropdown list, select the iteration to associate this issue with. +1. Select any area outside the dropdown list. + +Alternatively, you can use the `/iteration` [quick action](../quick_actions.md#issues-merge-requests-and-epics). + +## Copy issue reference + +To refer to an issue elsewhere in GitLab, you can use its full URL or a short reference, which looks like +`namespace/project-name#123`, where `namespace` is either a group or a username. + +To copy the issue reference to your clipboard: -You can also use the `/iteration` -[quick action](../quick_actions.md#issues-merge-requests-and-epics) -in a comment or description field. +1. Go to the issue. +1. On the right sidebar, next to **Reference**, select **Copy Reference** (**{copy-to-clipboard}**). + +You can now paste the reference into another description or comment. + +Read more about issue references in [GitLab-Flavored Markdown](../../markdown.md#gitlab-specific-references). + +## Copy issue email address + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18816) in GitLab 13.8. + +You can create a comment in an issue by sending an email. +Sending an email to this address creates a comment that contains the email body. + +To learn more about creating comments by sending an email and the necessary configuration, see +[Reply to a comment by sending email](../../discussions/index.md#reply-to-a-comment-by-sending-email). + +To copy the issue's email address: + +1. Go to the issue. +1. On the right sidebar, next to **Issue email**, select **Copy Reference** (**{copy-to-clipboard}**). ## Real-time sidebar @@ -393,35 +579,84 @@ On GitLab.com, this feature is available. Assignees in the sidebar are updated in real time. +## Assignee + +An issue can be assigned to one or [more users](multiple_assignees_for_issues.md). + +The assignees can be changed as often as needed. The idea is that the assignees are +people responsible for an issue. +When an issue is assigned to someone, it appears in their assigned issues list. + +If a user is not a member of a project, an issue can only be assigned to them if they create it +themselves or another project member assigns them. + +To change the assignee on an issue: + +1. Go to your issue. +1. On the right sidebar, in the **Assignee** section, select **Edit**. +1. From the dropdown list, select the user to add as an assignee. +1. Select any area outside the dropdown list. + ## Similar issues -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22866) in GitLab 11.6. +To prevent duplication of issues on the same topic, GitLab searches for similar issues +when you create a new issue. -To prevent duplication of issues for the same topic, GitLab searches for similar issues -when new issues are being created. +Prerequisites: -As you type in the title field of the **New Issue** page, GitLab searches titles and descriptions -across all issues to in the current project. Only issues you have access to are returned. -Up to five similar issues, sorted by most recently updated, are displayed below the title box. -[GraphQL](../../../api/graphql/index.md) must be enabled to use this feature. +- [GraphQL](../../../api/graphql/index.md) must be enabled. - +As you type in the title text box of the **New issue** page, GitLab searches titles and descriptions +across all issues in the current project. Only issues you have access to are returned. +Up to five similar issues, sorted by most recently updated, are displayed below the title text box. ## Health status **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in GitLab Ultimate 12.10. -> - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in GitLab Ultimate 13.4 and later. -> - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in GitLab Ultimate 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in GitLab 12.10. +> - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in GitLab 13.4 and later. +> - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in GitLab 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. To help you track issue statuses, you can assign a status to each issue. -This marks issues as progressing as planned or needs attention to keep on schedule: +This status marks issues as progressing as planned or needing attention to keep on schedule. + +Prerequisites: + +- You must have at least the [Reporter role](../../permissions.md) for the project. + +To edit health status of an issue: + +1. Go to the issue. +1. On the right sidebar, in the **Health status** section, select **Edit**. +1. From the dropdown list, select the status to add to this issue: -- On track (green) -- Needs attention (amber) -- At risk (red) + - On track (green) + - Needs attention (amber) + - At risk (red) + +You can then see the issue's status in the issues list and the epic tree. After an issue is closed, its health status can't be edited and the **Edit** button becomes disabled until the issue is reopened. -You can then see issue statuses in the issues list and the epic tree. +## Publish an issue **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.1. + +If a status page application is associated with the project, you can use the `/publish` +[quick action](../quick_actions.md) to publish the issue. + +For more information, see [GitLab Status Page](../../../operations/incident_management/status_page.md). + +## Issue-related quick actions + +You can also use [quick actions](../quick_actions.md#issues-merge-requests-and-epics) to manage issues. + +Some actions don't have corresponding UI buttons yet. +You can do the following **only by using quick actions**: + +- [Add or remove a Zoom meeting](associate_zoom_meeting.md) (`/zoom` and `/remove_zoom`). +- [Publish an issue](#publish-an-issue) (`/publish`). +- Clone an issue to the same or another project (`/clone`). +- Close an issue and mark as a duplicate of another issue (`/duplicate`). +- Copy labels and milestone from another merge request in the project (`/copy_metadata`). diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index 189777d40e7..98e940b6b51 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -12,8 +12,7 @@ In large teams, where there is shared ownership of an issue, it can be difficult to track who is working on it, who already completed their contributions, who didn't even start yet. -In [GitLab Enterprise Edition](https://about.gitlab.com/pricing/), -you can also select multiple assignees to an issue, making it easier to +You can also select multiple [assignees](managing_issues.md#assignee) for an issue, making it easier to track, and making clearer who is accountable for it.  diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index e4972181a5a..8a2a104c54d 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -26,7 +26,7 @@ To manage linked issues through our API, visit the [issue links API documentatio 1. Link one issue to another by selecting the add linked issue button (**{plus}**) in the **Linked issues** section of an issue. -1. Select the relationship the between the two issues. Either: +1. Select the relationship between the two issues. Either: - **relates to** - **blocks** **(PREMIUM)** - **is blocked by** **(PREMIUM)** diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index ebfc723280f..0340f15c25c 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -37,7 +37,7 @@ creation date. Issues created most recently are first. ## Sorting by due date When you sort by **Due date**, the issue list changes to sort ascending by the issue -[due date](issue_data_and_actions.md#due-date). Issues with the earliest due date are first, +[due date](due_dates.md). Issues with the earliest due date are first, and issues without a due date are last. ## Sorting by label priority diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index e9cbe012110..8874512f9c3 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -16,7 +16,7 @@ Labels are a key part of [issue boards](issue_board.md). With labels you can: - Categorize epics, issues, and merge requests using colors and descriptive titles like `bug`, `feature request`, or `docs`. - Dynamically filter and manage epics, issues, and merge requests. -- [Search lists of issues, merge requests, and epics](../search/index.md#issues-and-merge-requests), +- [Search lists of issues, merge requests, and epics](../search/index.md#search-issues-and-merge-requests), as well as [issue boards](../search/index.md#issue-boards). ## Project labels and group labels @@ -42,8 +42,8 @@ To assign or unassign a label: You can search repeatedly to add more labels. The selected labels are marked with a checkmark. 1. Click the labels you want to assign or unassign. -1. To apply your changes to labels, click **X** next to **Assign labels** or anywhere outside the - label section. +1. To apply your changes to labels, select **X** next to **Assign labels** or select any area + outside the label section. Alternatively, to unassign a label, click the **X** on the label you want to unassign. @@ -72,9 +72,9 @@ To create a new project label: 1. Select the **New label** button. 1. In the **Title** field, enter a short, descriptive name for the label. You can also use this field to create [scoped, mutually exclusive labels](#scoped-labels). -1. (Optional) In the **Description** field, you can enter additional +1. Optional. In the **Description** field, you can enter additional information about how and when to use this label. -1. (Optional) Select a background color for the label by selecting one of the +1. Optional. Select a background color for the label by selecting one of the available colors, or by entering a hex color value in the **Background color** field. 1. Select **Create label**. @@ -86,7 +86,7 @@ label section of the right sidebar of an issue or a merge request: 1. Click **Create project label**. - Fill in the name field. Note that you can't specify a description if creating a label this way. You can add a description later by editing the label (see below). - - (Optional) Select a color by clicking on the available colors, or input a hex + - Optional. Select a color by clicking on the available colors, or input a hex color value for a specific color. 1. Click **Create**. @@ -189,7 +189,7 @@ For example, filtering by the `platform::*` label returns issues that have `plat `platform::Android`, or `platform::Linux` labels. NOTE: -This is not available on the [issues or merge requests dashboard pages](../search/index.md#issues-and-merge-requests). +This is not available on the [issues or merge requests dashboard pages](../search/index.md#search-issues-and-merge-requests). ### Workflows with scoped labels diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index adf0a115c6e..283576fb4e9 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -52,7 +52,8 @@ Prerequisite: To add groups to a project: -1. Go to your project and select **Project information > Members**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. 1. On the **Invite group** tab, under **Select a group to invite**, choose a group. 1. Select the highest max [role](../../permissions.md) for users in the group. 1. Optional. Choose an expiration date. On that date, the user can no longer access the project. @@ -75,7 +76,8 @@ Prerequisite: To import users: -1. Go to your project and select **Project information > Members**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. 1. On the **Invite member** tab, at the bottom of the panel, select **Import**. 1. Select the project. You can view only the projects for which you're a maintainer. 1. Select **Import project members**. @@ -115,7 +117,8 @@ Prerequisites: To remove a member from a project: -1. Go to your project and select **Project information > Members**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. 1. Next to the project member you want to remove, select **Remove member** **{remove}**. 1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. @@ -136,7 +139,8 @@ You can filter and sort members in a project. ### Display inherited members -1. Go to your project and select **Project information > Members**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. 1. In the **Filter members** box, select `Membership` `=` `Inherited`. 1. Press Enter. @@ -144,7 +148,8 @@ You can filter and sort members in a project. ### Display direct members -1. Go to your project and select **Project information > Members**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. 1. In the **Filter members** box, select `Membership` `=` `Direct`. 1. Press Enter. @@ -166,7 +171,7 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last GitLab users can request to become a member of a project. -1. Go to the project you'd like to be a member of. +1. On the top bar, select **Menu > Projects** and find the project you want to be a member of. 1. By the project name, select **Request Access**.  @@ -189,8 +194,9 @@ Prerequisite: - You must be the project owner. -1. Go to the project and select **Settings > General**. -1. Expand the **Visibility, project features, permissions** section. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility, project features, permissions**. 1. Under **Project visibility**, select **Users can request access**. 1. Select **Save changes**. @@ -213,7 +219,8 @@ This feature might not be available to you. Check the **version history** note a In GitLab 13.11, you can optionally replace the form to add a member with a modal window. To add a member after enabling this feature: -1. Go to your project and select **Project information > Members**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. 1. Select **Invite members**. 1. Enter an email address and select a role. 1. Optional. Select an **Access expiration date**. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index abca140411a..4c96c4d9f56 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -4,7 +4,7 @@ group: Workspace info: 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 +# Share projects with other groups **(FREE)** You can share projects with other [groups](../../group/index.md). This makes it possible to add a group of users to a project with a single action. @@ -30,18 +30,20 @@ To share 'Project Acme' with the 'Engineering' group: 1. For 'Project Acme' use the left navigation menu to go to **Project information > Members**. 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 group is listed in the **Groups** tab. - - The project is listed on the group dashboard. +1. Optional. Select an expiration date. +1. Select **Invite**. + +After sharing 'Project Acme' with 'Engineering': + +- The group is listed in the **Groups** tab. +- The project is listed on the group dashboard. -Note that you can only share a project with: +You can share a project only 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 +- 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. -Administrators are able to share projects with any group in the system. +Administrators can share projects with any group in the system. ### Share a project modal window @@ -61,7 +63,7 @@ To share a project after enabling this feature: 1. Go to your project's page. 1. On the left sidebar, go to **Project information > Members**, and then select **Invite a group**. 1. Select a group, and select a **Max role**. -1. (Optional) Select an **Access expiration date**. +1. Optional. Select an **Access expiration date**. 1. Select **Invite**. ### Enable or disable modal window **(FREE SELF)** diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index d873f715557..dddd3925dbb 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -105,7 +105,7 @@ Without the approvals, the work cannot merge. Required approvals enable multiple - [Require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) before merging code that could introduce a vulnerability. **(ULTIMATE)** -## Related links +## Related topics - [Merge request approvals API](../../../../api/merge_request_approvals.md) - [Instance-level approval rules](../../../admin_area/merge_requests_approvals.md) for self-managed installations diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 1249aa826fa..f4393b2b76d 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -63,7 +63,7 @@ To edit a merge request approval rule: 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**, and then select **Edit**. -1. (Optional) Change the **Rule name**. +1. Optional. Change the **Rule name**. 1. Set the number of required approvals in **Approvals required**. The minimum value is `0`. 1. Add or remove eligible approvers, as needed: - *To add users or groups as approvers,* search for users or groups that are diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 56e93741c1a..a6ca9423df0 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -157,7 +157,7 @@ You can also enforce merge request approval settings: If the settings are inherited by a group or project, they cannot be changed in the group or project that inherited them. -## Related links +## Related topics - [Instance-level merge request approval settings](../../../admin_area/merge_requests_approvals.md) - [Compliance report](../../../compliance/compliance_report/index.md) diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index eff3a5bd99e..e59456e5b34 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -40,7 +40,7 @@ Consider the following workflow: ## How browser performance testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Browser Performance report artifact](../../../ci/yaml/index.md#artifactsreportsbrowser_performance). +[Browser Performance report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsbrowser_performance). GitLab then checks this report, compares key performance metrics for each page between the source and target branches, and shows the information in the merge request. @@ -89,7 +89,7 @@ The above example: GitLab 12.3 or earlier, you must [add the configuration manually](#gitlab-versions-132-and-earlier). The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), -and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/index.md#artifactsreportsbrowser_performance) +and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsbrowser_performance) that you can later download and analyze. This implementation always takes the latest Browser Performance artifact available. If [GitLab Pages](../pages/index.md) is enabled, you can view the report directly in your browser. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 4a2319774ac..15ba6e9de98 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -76,10 +76,10 @@ merge request is from a fork: 1. Click on the **Options** dropdown and select **Cherry-pick** to show the cherry-pick modal. 1. In **Pick into project** and **Pick into branch**, select the destination project and branch:  -1. (Optional) Select **Start a new merge request** if you're ready to create a merge request. +1. Optional. Select **Start a new merge request** if you're ready to create a merge request. 1. Click **Cherry-pick**. -## Related links +## Related topics - The [Commits API](../../../api/commits.md) enables you to add custom messages to changes you cherry-pick through the API. diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 9bfbbd8fc6f..b791bce5749 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -87,7 +87,7 @@ include: 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/yaml/index.md#artifactsreportscodequality) +[Code Quality report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportscodequality) that you can later download and analyze. It's also possible to override the URL to the Code Quality image by @@ -343,7 +343,7 @@ It's possible to have a custom tool provide Code Quality reports in GitLab. To do this: 1. Define a job in your `.gitlab-ci.yml` file that generates the - [Code Quality report artifact](../../../ci/yaml/index.md#artifactsreportscodequality). + [Code Quality report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportscodequality). 1. Configure your tool to generate the Code Quality report artifact as a JSON file that implements a subset of the [Code Climate spec](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types). diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index b615c86288c..bffb66755e0 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -7,15 +7,42 @@ type: reference, howto # Commit message templates **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) squash commit templates in GitLab 14.6. -## Merge commit message template +GitLab uses commit templates to create default messages for specific types of +commits. These templates encourage commit messages to follow a particular format, +or contain specific information. Users can override these templates when merging +a merge request. -As a project maintainer, you're able to configure merge commit message template. It will be used during merge to -create commit message. Template uses similar syntax to +Commit templates use syntax similar to the syntax for [review suggestions](reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). -Default merge commit message can be recreated using following template: +## Configure commit templates + +Change the commit templates for your project if the default templates don't +contain the information you need. + +Prerequisite: + +- You must have at least the Maintainer role for a project. + +To do this: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General** and expand **Merge requests**. +1. Depending on the type of template you want to create, scroll to either + [**Merge commit message template**](#default-template-for-merge-commits) or + [**Squash commit message template**](#default-template-for-squash-commits). +1. For your desired commit type, enter your default message. You can use both static + text and [variables](#supported-variables-in-commit-templates). Each template + is limited to a maximum of 500 characters, though after replacing the templates + with data, the final message may be longer. +1. Select **Save changes**. + +## Default template for merge commits + +The default template for merge commit messages is: ```plaintext Merge branch '%{source_branch}' into '%{target_branch}' @@ -27,25 +54,35 @@ Merge branch '%{source_branch}' into '%{target_branch}' See merge request %{reference} ``` -This commit message can be customized to follow any guidelines you might have. -To do so, expand the **Merge requests** tab within your project's **General** -settings and change the **Merge commit message template** text: +## Default template for squash commits + +If you have configured your project to [squash commits on merge](squash_and_merge.md), +GitLab creates a squash commit message with this template: + +```plaintext +%{title} +``` + +## Supported variables in commit templates + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/346805) `first_commit` and `first_multiline_commit` variables in GitLab 14.6. - +Commit message templates support these variables: -You can use static text and following variables: +| Variable | Description | Output example | +|----------|-------------|----------------| +| `%{source_branch}` | The name of the branch being merged. | `my-feature-branch` | +| `%{target_branch}` | The name of the branch that the changes are applied to. | `main` | +| `%{title}` | Title of the merge request. | `Fix tests and translations` | +| `%{issues}` | String with phrase `Closes <issue numbers>`. Contains all issues mentioned in the merge request description that match [issue closing patterns](../issues/managing_issues.md#closing-issues-automatically). Empty if no issues are mentioned. | `Closes #465, #190 and #400` | +| `%{description}` | Description of the merge request. | `Merge request description.`<br>`Can be multiline.` | +| `%{reference}` | Reference to the merge request. | `group-name/project-name!72359` | +| `%{first_commit}` | Full message of the first commit in merge request diff. | `Update README.md` | +| `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge Request title if all commits aren't multiline. | `Update README.md`<br><br>`Improved project description in readme file.` | -| Variable | Description | Output example | -|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------| -| `%{source_branch}` | The name of the branch that is being merged. | `my-feature-branch` | -| `%{target_branch}` | The name of the branch that the changes are applied to. | `master` | -| `%{title}` | Title of the merge request. | Fix stuff | -| `%{issues}` | String with phrase "Closes <issue numbers>" with all issues mentioned in the MR description matching [issue closing patterns](../issues/managing_issues.md#closing-issues-automatically). It will be empty when no issues were mentioned. | `Closes #465, #190 and #400` | -| `%{description}` | Description of the merge request. | Merge request description.<br>Can be multiline. | -| `%{reference}` | Reference to the merge request. | group-name/project-name!72359 | +Empty variables that are the only word in a line are removed, along with all newline characters preceding it. -NOTE: -Empty variables that are the only word in a line will be removed along with all newline characters preceding it. +## Related topics -Merge commit template field has a limit of 500 characters. This limit only applies to the template -itself. +- [Squash and merge](squash_and_merge.md). diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md index ff2e6acf123..10c63421876 100644 --- a/doc/user/project/merge_requests/confidential.md +++ b/doc/user/project/merge_requests/confidential.md @@ -70,7 +70,7 @@ Open a merge request - You are satisfied the problem is resolved in your private fork. - You are ready to make the confidential commits public. -## Related links +## Related topics - [Confidential issues](../issues/confidential_issues.md) - [Make an epic confidential](../../group/epics/manage_epics.md#make-an-epic-confidential) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 918f9830edc..220049d9a88 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -21,6 +21,10 @@ You can create a merge request from the list of merge requests. 1. Select a source and target branch and then **Compare branches and continue**. 1. Fill out the fields and select **Create merge request**. +NOTE: +Merge requests are designed around a one-to-one (1:1) branch relationship. Only one open merge request may +be associated with a given target branch at a time. + ## From an issue You can [create a merge request from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). @@ -155,6 +159,8 @@ branch already exists, the patches are applied on top of it. ## Set the default target project +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/58093) in GitLab 13.11. + Merge requests have a source and a target project that are the same, unless forking is involved. Creating a fork of the project can cause either of these scenarios when you create a new merge request: diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 006e6d4a8aa..323b7505190 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -88,7 +88,7 @@ Choose an assignee to designate someone as the person responsible for the first [review of the merge request](reviews/index.md). Open the drop down box to search for the user you wish to assign, and the merge request is added to their -[assigned merge request list](../../search/index.md#issues-and-merge-requests). +[assigned merge request list](../../search/index.md#search-issues-and-merge-requests). #### Multiple assignees **(PREMIUM)** @@ -136,10 +136,18 @@ To learn more, read [Review a merge request](reviews/index.md). ### Merge requests to close issues -If the merge request is being created to resolve an issue, you can -add a note in the description which sets it to -[automatically close the issue](../issues/managing_issues.md#closing-issues-automatically) -when merged. +To create a merge request to close an issue when it's merged, you can either: + +- [Add a note in the MR description](../issues/managing_issues.md#closing-issues-automatically). +- In the issue, select **Create a merge request**. Then, you can either: + + - Create a new branch and [a draft merge request](../merge_requests/drafts.md) + in one action. The branch is named `issuenumber-title` by default, but you can + choose any name, and GitLab verifies that it's 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. + - Create a [new branch](../repository/web_editor.md#create-a-new-branch-from-an-issue) + only, with its name starting with the issue number. If the issue is [confidential](../issues/confidential_issues.md), you may want to use a different workflow for diff --git a/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png b/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png Binary files differdeleted file mode 100644 index f18ca640d38..00000000000 --- a/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 54b97eb5732..8222d696853 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -74,7 +74,7 @@ change and whether you need access to a development environment: If you decide to permanently stop work on a merge request, GitLab recommends you close the merge request rather than -[delete it](#delete-a-merge-request). Users with +[delete it](#delete-a-merge-request). The author and assignees of a merge request, and users with Developer, Maintainer, or Owner [roles](../../permissions.md) in a project can close merge requests in the project: diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 1d892a3c2e1..7b157aa94d8 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -28,7 +28,7 @@ GET calls to a popular API endpoint in your application to see how it performs. ## How Load Performance Testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Load Performance report artifact](../../../ci/yaml/index.md#artifactsreportsload_performance). +[Load Performance report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsload_performance). GitLab checks this report, compares key load performance metrics between the source and target branches, and then shows the information in a merge request widget: @@ -140,7 +140,7 @@ For example, you can override the duration of the test with a CLI option: GitLab only displays the key performance metrics in the MR widget if k6's results are saved via [summary export](https://k6.io/docs/results-visualization/json#summary-export) -as a [Load Performance report artifact](../../../ci/yaml/index.md#artifactsreportsload_performance). +as a [Load Performance report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsload_performance). The latest Load Performance artifact available is always used, using the summary values from the test. @@ -161,7 +161,7 @@ such as: ``http.get(`${__ENV.ENVIRONMENT_URL}`)``. For example: 1. In the `review` job: - 1. Capture the dynamic URL and save it into a `.env` file, e.g. `echo "ENVIRONMENT_URL=$CI_ENVIRONMENT_URL" >> review.env`. + 1. Capture the dynamic URL and save it into a `.env` file, for example, `echo "ENVIRONMENT_URL=$CI_ENVIRONMENT_URL" >> review.env`. 1. Set the `.env` file to be a [job artifact](../../../ci/pipelines/job_artifacts.md#job-artifacts). 1. In the `load_performance` job: 1. Set it to depend on the review job, so it inherits the environment file. diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 597dcb3dfb9..c34a8116625 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -43,7 +43,7 @@ To start your review: - **Add to review**: Keep this comment private and add to the current review. These review comments are marked **Pending** and are visible only to you. - **Add comment now**: Submits the specific comment as a regular comment instead of as part of the review. -1. (Optional) You can use [quick actions](../../quick_actions.md) inside review comments. +1. Optional. You can use [quick actions](../../quick_actions.md) inside review comments. The comment shows the actions to perform after publication, but does not perform them until you submit your review. 1. When your review is complete, you can [submit the review](#submit-a-review). Your comments @@ -72,7 +72,7 @@ When you submit your review, GitLab: ### Resolve or unresolve thread with a comment -Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolve-a-thread)). +Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolve-a-thread). When replying to a comment, a checkbox is displayed to resolve or unresolve the thread after publication. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 7bfb8e52279..c25b9e15974 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -144,6 +144,6 @@ to your branch to address your reviewers' requests. WARNING: Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions. -## Related links +## Related topics - [Suggestions API](../../../../api/suggestions.md) diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index c3fc2fa871f..3fe82fb8ef3 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -29,11 +29,9 @@ The squashed commit in this example is followed by a merge commit, because the m **Project Settings > General > Merge requests > Merge method > Fast-forward merge**. The squashed commit's default commit message is taken from the merge request title. +You can [edit the default message for squash commits](commit_templates.md). -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. +It can also be customized before merging a merge request.  @@ -126,6 +124,10 @@ 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. +## Related topics + +- [Commit message templates](commit_templates.md). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 08b82462187..f5ebfb3668c 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -181,6 +181,6 @@ You should: - Check the [GitLab status page](https://status.gitlab.com/) if the problem persists, to see if there is a wider outage. -## Related links +## Related topics - [External status checks API](../../../api/status_checks.md) diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index b36510c2df8..1f84964c619 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -29,7 +29,7 @@ between pipeline completion and the visualization loading on the page. For the coverage analysis to work, you have to provide a properly formatted [Cobertura XML](https://cobertura.github.io/cobertura/) report to -[`artifacts:reports:cobertura`](../../../ci/yaml/index.md#artifactsreportscobertura). +[`artifacts:reports:cobertura`](../../../ci/yaml/artifacts_reports.md#artifactsreportscobertura). This format was originally developed for Java, but most coverage analysis frameworks for other languages have plugins to add support for it, like: @@ -52,10 +52,15 @@ from any job in any stage in the pipeline. The coverage displays for each line: Hovering over the coverage bar provides further information, such as the number of times the line was checked by tests. -NOTE: +### Limits + A limit of 100 `<source>` nodes for Cobertura format XML files applies. If your Cobertura report exceeds 100 nodes, there can be mismatches or no matches in the merge request diff view. +A single Cobertura XML file can be no more than 10MiB. For large projects, split the Cobertura XML into +smaller files. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/328772) for more details. +When submitting many files, it can take a few minutes for coverage to show on a merge request. + ### Artifact expiration By default, the [pipeline artifact](../../../ci/pipelines/pipeline_artifacts.md#storage) used diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 3922ee4d770..796ffc7866c 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -2,10 +2,9 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, concepts --- -# Merge requests versions +# Merge requests versions **(FREE)** Every time you push to a branch that is tied to a merge request, a new version of merge request diff is created. When you visit a merge request that contains diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 3f7d5b6aac1..fb61e123faf 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -119,7 +119,7 @@ Every issue and merge request can be assigned a milestone. The milestones are vi ### Filtering in list pages -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. +From the project and group issue/merge request list pages, you can [filter](../../search/index.md#search-issues-and-merge-requests) by both group and project milestones. ### Filtering in issue boards 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 410fdab15e7..165131d50a4 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 @@ -36,12 +36,15 @@ for the most popular hosting services: - [Bluehost](https://www.bluehost.com/help/article/dns-management-add-edit-or-delete-dns-entries) - [Cloudflare](https://support.cloudflare.com/hc/en-us/articles/201720164-Creating-a-Cloudflare-account-and-adding-a-website) - [cPanel](https://documentation.cpanel.net/display/84Docs/Edit+DNS+Zone) +- [DigitalOcean](https://docs.digitalocean.com/products/networking/dns/how-to/manage-records/) - [DreamHost](https://help.dreamhost.com/hc/en-us/articles/215414867-How-do-I-add-custom-DNS-records-) +- [Gandi](https://docs.gandi.net/en/domain_names/faq/dns_records.html) - [Go Daddy](https://www.godaddy.com/help/add-an-a-record-19238) - [Hostgator](https://www.hostgator.com/help/article/changing-dns-records) - [Inmotion hosting](https://www.bluehost.com/help/article/dns-management-add-edit-or-delete-dns-entries) - [Media Temple](https://mediatemple.net/community/products/dv/204403794/how-can-i-change-the-dns-records-for-my-domain) - [Microsoft](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-2000-server/bb727018(v=technet.10)) +- [Namecheap](https://www.namecheap.com/support/knowledgebase/subcategory/2237/host-records-setup/) <!-- vale gitlab.Spelling = YES --> 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 ee4320d5ea1..ec66dce41f9 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 @@ -25,7 +25,8 @@ and steps below. (`*.gitlab.io`, for GitLab.com). - A custom domain name `example.com` or subdomain `subdomain.example.com`. - Access to your domain's server control panel to set up DNS records: - - A DNS A or CNAME record pointing your domain to GitLab Pages server. + - A DNS record (`A`, `ALIAS`, or `CNAME`) pointing your domain to the GitLab Pages server. If + there are multiple DNS records on that name, you must use an `ALIAS` record. - A DNS `TXT` record to verify your domain's ownership. - Set either `external_http` or `external_https` in `/etc/gitlab/gitlab.rb` to the IP and port of your [Pages Daemon](../../../../administration/pages/index.md#overview). @@ -109,15 +110,15 @@ as it most likely doesn't work if you set an [`MX` record](dns_concepts.md#mx-re Subdomains (`subdomain.example.com`) require: -- A DNS [CNAME record](dns_concepts.md#cname-record) pointing your subdomain to the Pages server. +- A DNS [`ALIAS` or `CNAME` record](dns_concepts.md#cname-record) pointing your subdomain to the Pages server. - A DNS [TXT record](dns_concepts.md#txt-record) to verify your domain's ownership. -| From | DNS Record | To | -| ------------------------------------------------------- | ---------- | --------------------- | -| `subdomain.example.com` | CNAME | `namespace.gitlab.io` | -| `_gitlab-pages-verification-code.subdomain.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| From | DNS Record | To | +|:--------------------------------------------------------|:----------------|:----------------------| +| `subdomain.example.com` | `ALIAS`/`CNAME` | `namespace.gitlab.io` | +| `_gitlab-pages-verification-code.subdomain.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -Note that, whether it's a user or a project website, the `CNAME` +Note that, whether it's a user or a project website, the DNS record should point to your Pages domain (`namespace.gitlab.io`), without any `/project-name`. @@ -130,8 +131,8 @@ domain to the same website, for instance, `example.com` and `www.example.com`. They require: -- A DNS A record for the domain. -- A DNS CNAME record for the subdomain. +- A DNS `A` record for the domain. +- A DNS `ALIAS`/`CNAME` record for the subdomain. - A DNS `TXT` record for each. | From | DNS Record | To | @@ -147,7 +148,7 @@ If you're using Cloudflare, check > **Notes**: > -> - **Do not** use a CNAME record if you want to point your +> - **Do not** use a `CNAME` record if you want to point your `domain.com` to your GitLab Pages site. Use an `A` record instead. > - **Do not** add any special chars after the default Pages domain. For example, don't point `subdomain.domain.com` to @@ -231,7 +232,7 @@ If you use Cloudflare, you can redirect `www` to `domain.com` without adding both `www.domain.com` and `domain.com` to GitLab. To do so, you can use Cloudflare's page rules associated to a -CNAME record to redirect `www.domain.com` to `domain.com`. You +`CNAME` record to redirect `www.domain.com` to `domain.com`. You can use the following setup: 1. In Cloudflare, create a DNS `A` record pointing `domain.com` to `35.185.44.232`. 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 ee1004a3416..75fc407ce3f 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 @@ -67,7 +67,7 @@ associated Pages domain. GitLab also renews it automatically. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30146) in GitLab 13.0. -If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, first, make sure that your pages site is set to "Everyone" in your project's **Settings > General > Visbility**. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps: +If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, first, make sure that your pages site is set to "Everyone" in your project's **Settings > General > Visibility**. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps: 1. Go to your project's **Settings > Pages**. 1. Click **Edit** on your domain. 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 386ed566225..b43af2f0efe 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 @@ -18,9 +18,9 @@ configured to generate a Pages site. To fork a sample project and create a Pages website: 1. View the sample projects by navigating to the [GitLab Pages examples](https://gitlab.com/pages) group. -1. Click the name of the project you want to [fork](../../../../user/project/working_with_projects.md#fork-a-project). -1. In the top right, click the **Fork** button, and then choose a namespace to fork to. -1. Go to your project's **CI/CD > Pipelines** and click **Run pipeline**. +1. Select the name of the project you want to [fork](../../repository/forking_workflow.md#creating-a-fork). +1. In the top right, select **Fork** and then choose a namespace to fork to. +1. For your project, on the left sidebar, select **CI/CD > Pipelines** and then **Run pipeline**. GitLab CI/CD builds and deploys your site. The site can take approximately 30 minutes to deploy. @@ -31,13 +31,13 @@ that immediately publishes your changes to the Pages site. You can take some **optional** further steps: -- _Remove the fork relationship._ If you want to contribute to the project you forked from, +- Remove the fork relationship. If you want to contribute to the project you forked from, you can keep this relationship. Otherwise, go to your project's **Settings > General**, expand **Advanced settings**, and scroll down to **Remove fork relationship**:  -- _Change the URL to match your namespace._ If your Pages site is hosted on GitLab.com, +- Change the URL to match your namespace. If your Pages site is hosted on GitLab.com, you can rename it to `<namespace>.gitlab.io`, where `<namespace>` is your GitLab namespace (the one you chose when you forked the project). 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 eb5f3a1bbf0..e0c10e27ec3 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -27,7 +27,7 @@ To create a GitLab Pages website: ## Prerequisites -You must have a [blank project](../../working_with_projects.md#blank-projects) in GitLab. +You must have a [blank project](../../working_with_projects.md#create-a-blank-project) in GitLab. ## Create the project files 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 978e35b3a9f..1f60aafe71b 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -1,165 +1,9 @@ --- -stage: Release -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)." +redirect_to: 'custom_domains_ssl_tls_certification/lets_encrypt_integration.md' +remove_date: '2022-03-14' --- -# Let's Encrypt for GitLab Pages (manual process, deprecated) **(FREE)** +This file was moved to [another location](custom_domains_ssl_tls_certification/lets_encrypt_integration.md). -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/TLS certificate. - -[Let's Encrypt](https://letsencrypt.org) is a free, automated, and -open source Certificate Authority. - -## Requirements - -To follow along with this tutorial, we assume you already have: - -- [Created a project](index.md#getting-started) in GitLab - containing your website's source code. -- Acquired a domain (`example.com`) and added a [DNS entry](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain) - pointing it to your Pages website. -- [Added your domain to your Pages project](custom_domains_ssl_tls_certification/index.md#steps) - and verified your ownership. -- Cloned your project into your computer. -- Your website up and running, served under HTTP protocol at `http://example.com`. - -## Obtaining a Let's Encrypt certificate - -Once you have the requirements addressed, follow the instructions -below to learn how to obtain the certificate. - -Note that these instructions were tested on macOS Mojave. For other operating systems the steps -might be slightly different. Follow the -[CertBot instructions](https://certbot.eff.org/) according to your OS. - -1. On your computer, open a terminal and navigate to your repository's - root directory: - - ```shell - cd path/to/dir - ``` - -1. Install CertBot (the tool Let's Encrypt uses to issue certificates): - - ```shell - brew install certbot - ``` - -1. Request a certificate for your domain (`example.com`) and - provide an email account (`your@email.com`) to receive notifications: - - ```shell - sudo certbot certonly -a manual -d example.com --email your@email.com - ``` - - Alternatively, you can register without adding an email account, - but you aren't notified about the certificate expiration's date: - - ```shell - sudo certbot certonly -a manual -d example.com --register-unsafely-without-email - ``` - - NOTE: - Read through CertBot's documentation on their - [command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options). - -1. You're prompted with a message to agree with their terms. - Press `A` to agree and `Y` to let they log your IP. - - CertBot then prompts you with the following message: - - ```shell - Create a file containing just this data: - - Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb - - And make it available on your web server at this URL: - - http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP - - Press Enter to Continue - ``` - -1. **Do not press Enter yet.** Let's Encrypt needs to verify your - domain ownership before issuing the certificate. To do so, create 3 - consecutive directories under your website's root: - `/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP/` - and add to the last folder an `index.html` file containing the content - referred on the previous prompt message: - - ```shell - Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb - ``` - - Note that this file needs to be accessed under - `http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP` - to allow Let's Encrypt to verify the ownership of your domain, - therefore, it needs to be part of the website content under the - repository's [`public`](index.md#how-it-works) folder. - -1. Add, commit, and push the file into your repository in GitLab. Once the pipeline - passes, press **Enter** on your terminal to continue issuing your - certificate. CertBot then prompts you with the following message: - - ```shell - Waiting for verification... - Cleaning up challenges - - IMPORTANT NOTES: - - Congratulations! Your certificate and chain have been saved at: - /etc/letsencrypt/live/example.com/fullchain.pem - Your key file has been saved at: - /etc/letsencrypt/live/example.com/privkey.pem - Your cert will expire on 2019-03-12. To obtain a new or tweaked - version of this certificate in the future, simply run certbot - again. To non-interactively renew *all* of your certificates, run - "certbot renew" - - If you like Certbot, please consider supporting our work by: - - Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate - Donating to EFF: https://eff.org/donate-le - ``` - -## Add your certificate to GitLab Pages - -Now that your certificate has been issued, let's add it to your Pages site: - -1. Back at GitLab, navigate to your project's **Settings > Pages**, - find your domain and click **Details** and **Edit** to add your certificate. -1. From your terminal, copy and paste the certificate into the first field - **Certificate (PEM)**: - - ```shell - sudo cat /etc/letsencrypt/live/example.com/fullchain.pem | pbcopy - ``` - -1. Copy and paste the private key into the second field **Key (PEM)**: - - ```shell - sudo cat /etc/letsencrypt/live/example.com/privkey.pem | pbcopy - ``` - -1. Click **Save changes** to apply them to your website. -1. Wait a few minutes for the configuration changes to take effect. -1. Visit your website at `https://example.com`. - -To force `https` connections on your site, navigate to your -project's **Settings > Pages** and check **Force HTTPS (requires -valid certificates)**. - -## Renewal - -Let's Encrypt certificates expire every 90 days and you must -renew them periodically. To renew all your certificates at once, run: - -```shell -sudo certbot renew -``` +<!-- This redirect file can be deleted after <2022-03-14>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 3deea92f56e..beafbc86cb5 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -92,7 +92,7 @@ you can explicitly set your own. The following HTTP codes are supported: > - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. > - Enabled on GitLab.com. -> - Enabled by default in self-managed GitLab behind the [`FF_ENABLE_REDIRECTS` feature flag](#feature-flag-for-redirects). +> - Enabled on self-managed in [GitLab 14.6](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/618). To create a redirect, add a rule that includes a `from` path, a `to` path, and an [HTTP status code](#http-status-codes): @@ -261,36 +261,7 @@ However, there are some minor differences: literal `:placeholder`). - GitLab redirects to `/new/`. -## Features behind feature flags - -Some Pages features are behind feature flags. - -### Feature flag for redirects - -FLAG: -Redirects in GitLab Pages is under development, and is deployed behind a feature flag -that is **enabled by default**. - -To disable redirects, for [Omnibus installations](../../../administration/pages/index.md), define the -`FF_ENABLE_REDIRECTS` environment variable in the -[global settings](../../../administration/pages/index.md#global-settings). -Add the following line to `/etc/gitlab/gitlab.rb` and -[reconfigure the instance](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - -```ruby -gitlab_pages['env']['FF_ENABLE_REDIRECTS'] = 'false' -``` - -For [source installations](../../../administration/pages/source.md), define the -`FF_ENABLE_REDIRECTS` environment variable, then -[restart GitLab](../../../administration/restart_gitlab.md#installations-from-source): - -```shell -export FF_ENABLE_REDIRECTS="false" -/path/to/pages/bin/gitlab-pages -config gitlab-pages.conf -``` - -### Feature flag for rewrites +## Feature flag for rewrites FLAG: Rewrites in GitLab Pages is under development, and is deployed behind a feature flag diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index a4d7b94506b..75a5a2a6a4f 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -35,7 +35,7 @@ If you manually enter a parameter, it must be enclosed in double quotation marks - ASCII letters - Numbers (0-9) -- Underscore (`_`), hyphen (`-`), question mark (`?`), dot (`.`), or ampersand (`&`) +- Underscore (`_`), hyphen (`-`), question mark (`?`), dot (`.`), ampersand (`&`) or at (`@`) Parameters are case-sensitive. Autocomplete handles this, and the insertion of quotation marks, automatically. @@ -45,14 +45,15 @@ of quotation marks, automatically. The following quick actions are applicable to descriptions, discussions, and threads. Some quick actions might not be available to all subscription tiers. +<!-- Keep this table sorted alphabetically --> + | Command | Issue | Merge request | Epic | Action | |:--------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| +| `/add_contacts email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | | `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. | -| `/assign @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one user. | -| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign multiple users. | +| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users. | | `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. | -| `/assign_reviewer @user` or `/reviewer @user` or `/request_review @user` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one user as a reviewer. | -| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign multiple users as reviewers. | +| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. | | `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. | | `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle emoji award. | | `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | @@ -81,11 +82,12 @@ threads. Some quick actions might not be available to all subscription tiers. | `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced in GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/issues/296787)). | | `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) | | `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | -| `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | | `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. | +| `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | | `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | | `/relate #issue1 #issue2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark issues as related. | | `/remove_child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | +| `/remove_contacts email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | | `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove due date. | | `/remove_epic` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove from epic. | | `/remove_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. | diff --git a/doc/user/project/releases/img/feature_count_v14_6.png b/doc/user/project/releases/img/feature_count_v14_6.png Binary files differnew file mode 100644 index 00000000000..0b1a0552631 --- /dev/null +++ b/doc/user/project/releases/img/feature_count_v14_6.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index abedae5d10b..239e6c9cea8 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -1,5 +1,4 @@ --- -type: reference, howto stage: Release 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 @@ -9,26 +8,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7. -To introduce a checkpoint in your source code history, you can assign a -[Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) at the moment of release. -However, in most cases, your users need more than just the raw source code. -They need compiled objects or other assets output by your CI/CD system. +In GitLab, a release enables you to create a snapshot of your project for your users, including +installation packages and release notes. You can create a GitLab release on any branch. Creating a +release also creates a [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to mark the +release point in the source code. -A GitLab Release can be: +WARNING: +Deleting a Git tag associated with a release also deletes the release. + +A release can include: - A snapshot of the source code of your repository. - [Generic packages](../../packages/generic_packages/index.md) created from job artifacts. - Other metadata associated with a released version of your code. +- Release notes. -You can create a GitLab release on any branch. When you create a release: +When you [create a release](#create-a-release): - GitLab automatically archives source code and associates it with the release. - GitLab automatically creates a JSON file that lists everything in the release, so you can compare and audit releases. This file is called [release evidence](#release-evidence). -- You can add release notes and a message for the tag associated with the release. -After you create a release, you can [associate milestones with it](#associate-milestones-with-a-release), -and attach [release assets](#release-assets), like runbooks or packages. +When you create a release, or after, you can: + +- Add release notes. +- Add a message for the Git tag associated with the release. +- [Associate milestones with it](#associate-milestones-with-a-release). +- Attach [release assets](#release-assets), like runbooks or packages. ## View releases @@ -46,49 +52,84 @@ To view a list of releases: - On private projects, this number is visible to users with Reporter [permissions](../../permissions.md#project-members-permissions) or higher. -### Sort Releases +### Sort releases -On the top right of the **Releases** page, you can use the sorting button to order releases by -**Released date** or **Created date**. You can sort releases in ascending or descending order. +To sort releases by **Released date** or **Created date**, select from the sort order dropdown. To +switch between ascending or descending order, select **Sort order**. - + ## Create a release > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32812) in GitLab 12.9. Releases can be created directly in the GitLab UI. -You can create a release in the user interface, or by using the -[Releases API](../../../api/releases/index.md#create-a-release). -We recommend using the API to create releases as one of the last steps in your -CI/CD pipeline. +You can create a release: -Only users with at least the Developer role can create releases. -Read more about [Release permissions](#release-permissions). +- [Using a job in your CI/CD pipeline](#create-a-release-by-using-a-cicd-job). +- [In the Releases page](#create-a-release-in-the-releases-page). +- [In the Tags page](#create-a-release-in-the-tags-page). +- Using the [Releases API](../../../api/releases/index.md#create-a-release). + +We recommend creating a release as one of the last steps in your CI/CD pipeline. + +Prerequisites: + +- You must have at least the Developer role for a project. For more information, read +[Release permissions](#release-permissions). + +### Create a release in the Releases page -To create a new release through the GitLab UI: +To create a release in the Releases page: +1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Releases** and select **New release**. -1. Open the [**Tag name**](#tag-name) dropdown. Select an existing tag or type - in a new tag name. Selecting an existing tag that is already associated with - a release will result in a validation error. -1. If creating a new tag, open the **Create from** dropdown. Select a - branch, tag, or commit SHA to use when creating the new tag. -1. Optionally, fill out any additional information about the release, such as its - [title](#title), [milestones](#associate-milestones-with-a-release), - [release notes](#release-notes-description), or [assets links](#links). -1. Click **Create release**. - -## Create a release by using a CI/CD job +1. From the [**Tag name**](#tag-name) dropdown, either: + - Select an existing Git tag. Selecting an existing tag that is already associated with a release + results in a validation error. + - Enter a new Git tag name. + 1. From the **Create from** dropdown, select a branch or commit SHA to use when creating the + new tag. +1. Optional. Enter additional information about the release, including: + - [Title](#title). + - [Milestones](#associate-milestones-with-a-release). + - [Release notes](#release-notes-description). + - [Asset links](#links). +1. Select **Create release**. + +### Create a release in the Tags page + +To create a release in the Tags page, add release notes to either an existing or a new Git tag. + +To add release notes to a new Git tag: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Tags**. +1. Select **New tag**. +1. Optional. Enter a tag message in the **Message** text box. +1. In the **Release notes** text box, enter the release's description. + You can use Markdown and drag and drop files to this text box. +1. Select **Create tag**. + +To edit release notes of an existing Git tag: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Tags**. +1. Select **Edit release notes** (**{pencil}**). +1. In the **Release notes** text box, enter the release's description. + You can use Markdown and drag and drop files to this text box. +1. Select **Save changes**. + +### Create a release by using a CI/CD job > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19298) in GitLab 12.7. You can create a release directly as part of the GitLab CI/CD pipeline -by using [the `release` keyword](../../../ci/yaml/index.md#release) in the job definition. +by using the [`release` keyword](../../../ci/yaml/index.md#release) 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. +The release is created only if the job processes without error. If the API returns an error during +release creation, the release job fails. -### CI/CD example of the `release` keyword +#### CI/CD example of the `release` keyword To create a release when you push a Git tag, or when you add a Git tag in the UI by going to **Repository > Tags**: @@ -100,7 +141,7 @@ release_job: rules: - if: $CI_COMMIT_TAG # Run this job when a tag is created manually script: - - echo 'running release_job' + - echo "running release_job" release: name: 'Release $CI_COMMIT_TAG' description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION must be defined @@ -149,7 +190,7 @@ release_job: when: never # Do not run this job when a tag is created manually - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch script: - - echo 'running release_job for $TAG' + - echo "running release_job for $TAG" release: name: 'Release $TAG' description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION and the $TAG @@ -207,7 +248,7 @@ which requires the text representation of the certificate. ### `release-cli` command line -The entries under the `release` node are transformed into a `bash` command line and sent +The entries under the `release` node are transformed into Bash commands and sent to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli). You can also call the `release-cli` directly from a `script` entry. @@ -224,14 +265,14 @@ A pipeline can have multiple `release` jobs, for example: ```yaml ios-release: script: - - echo 'iOS release job' + - echo "iOS release job" release: tag_name: v1.0.0-ios description: 'iOS release v1.0.0' android-release: script: - - echo 'Android release job' + - echo "Android release job" release: tag_name: v1.0.0-android description: 'Android release v1.0.0' @@ -255,7 +296,8 @@ release tag. When the `released_at` date and time has passed, the badge is autom ## Edit a release -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26016) in GitLab 12.6. Asset link editing was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9427) in GitLab 12.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26016) in GitLab 12.6. +> - Asset link editing [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9427) in GitLab 12.10. Only users with at least the Developer role can edit releases. Read more about [Release permissions](#release-permissions). @@ -271,29 +313,6 @@ You can edit the release title, notes, associated milestones, and asset links. To change the release date use the [Releases API](../../../api/releases/index.md#update-a-release). -## Add release notes to Git tags - -If you have an existing Git tag, you can add release notes to it. - -You can do this in the user interface, or by using the [Releases API](../../../api/releases/index.md). -We recommend using the API to add release notes as one of the last steps in your CI/CD release pipeline. - -In the interface, to add release notes to a new Git tag: - -1. Navigate to your project's **Repository > Tags**. -1. Click **New tag**. -1. In the **Release notes** field, enter the release's description. - You can use Markdown and drag and drop files to this field. -1. Click **Create tag**. - -In the interface, to add release notes to an existing Git tag: - -1. Navigate to your project's **Repository > Tags**. -1. Click **Edit release notes** (the pencil icon). -1. In the **Release notes** field, enter the release's description. - You can use Markdown in this field, and drag and drop files to it. -1. Click **Save changes**. - ## Associate milestones with a release > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29020) in GitLab 12.5. @@ -325,6 +344,11 @@ Here is an example of milestones with no releases, one release, and two releases  +NOTE: +A subgroup's project releases cannot be associated with a supergroup's milestone. To learn +more, read issue #328054, +[Releases cannot be associated with a supergroup milestone](https://gitlab.com/gitlab-org/gitlab/-/issues/328054). + ## Get notified when a release is created > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26001) in GitLab 12.4. @@ -576,6 +600,29 @@ links to a release is not recommended, because artifacts are ephemeral and are used to pass data in the same pipeline. This means there's a risk that they could either expire or someone might manually delete them. +#### Number of new and total features **(FREE SAAS)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235618) in GitLab 13.5. + +On [GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/releases), you can view the number of new and total features in the project. + + + +The totals are displayed on [shields](https://shields.io/) and are generated per release by +[a Rake task in the `www-gitlab-com` repo](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/lib/tasks/update_gitlab_project_releases_page.rake). + +| Item | Formula | +| ------ | ------ | +| `New features` | Total count of release posts across all tiers for a single release in the project. | +| `Total features` | Total count of release posts in reverse order for all releases in the project. | + +The counts are also shown by license tier. + +| Item | Formula | +| ------ | ------ | +| `New features` | Total count of release posts across a single tier for a single release in the project. | +| `Total features` | Total count of release posts across a single tier in reverse order for all releases in the project. | + ## Release evidence > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. @@ -776,7 +823,7 @@ You can copy the example project to your own group or instance for testing. More ### Getting `403 Forbidden` or `Something went wrong while creating a new release` errors when creating, updating or deleting releases and their assets -If the release is associted with a [protected tag](../protected_tags.md), +If the release is associated with a [protected tag](../protected_tags.md), the UI/API request might result in an authorization failure. Make sure that the user or a service/bot account is allowed to [create the protected tag](../protected_tags.md#configuring-protected-tags) too. diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index c23ceaa1aba..b55f0b0a734 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -1,11 +1,10 @@ --- -type: reference, howto stage: Release 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 --- -# Install the `release-cli` for the Shell executor +# Install the `release-cli` for the Shell executor **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/release-cli/-/issues/21) in GitLab 13.8. > - [Changed](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/108) in GitLab 14.2, the `release-cli` binaries are also [available in the Package Registry](https://gitlab.com/jaime/release-cli/-/packages). diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index bc6bc799670..65b7c4a9881 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -41,7 +41,7 @@ To update the default branch name for an individual [project](../../index.md): 1. Sign in to GitLab with at least the [Maintainer](../../../permissions.md) role. 1. In the left navigation menu, go to **Settings > Repository**. 1. Expand **Default branch**, and select a new default branch. -1. (Optional) Select the **Auto-close referenced issues on default branch** checkbox to close +1. Optional. Select the **Auto-close referenced issues on default branch** checkbox to close issues when a merge request [uses a closing pattern](../../issues/managing_issues.md#closing-issues-automatically). 1. Select **Save changes**. @@ -134,7 +134,7 @@ renames a Git repository's (`example`) default branch. [change the default branch for this project](#change-the-default-branch-name-for-a-project). Select `main` as your new default branch. 1. Protect your new `main` branch as described in the [protected branches documentation](../../protected_branches.md). -1. (Optional) If you want to delete the old default branch: +1. Optional. If you want to delete the old default branch: 1. Verify that nothing is pointing to it. 1. Delete the branch on the remote: diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index bf4ef21e31b..1ab21286a8e 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -26,17 +26,17 @@ To fork an existing project in GitLab: 1. Select the project to fork to: - - *(Recommended method)* Below **Select a namespace to fork the project**, identify + - Recommended method. Below **Select a namespace to fork the project**, identify the project you want to fork to, and click **Select**. Only namespaces you have Developer and higher [permissions](../../permissions.md) for are shown.  - - *(Experimental method)* If your GitLab administrator has + - Experimental method. If your GitLab administrator has [enabled the experimental fork project form](#enable-or-disable-the-fork-project-form), read [Create a fork with the fork project form](#create-a-fork-with-the-fork-project-form). - Only namespaces you have Developer and higher - [permissions](../../permissions.md) for are shown. + Only namespaces you have at least the Developer + [role](../../permissions.md) for are shown. NOTE: The project path must be unique in the namespace. @@ -101,7 +101,7 @@ To use it, follow the instructions at [Creating a fork](#creating-a-fork) and pr - The project name. - The project URL. - The project slug. -- *(Optional)* The project description. +- Optional. The project description. - The visibility level for your fork. ### Enable or disable the fork project form **(FREE SELF)** diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 6aa32b1b816..27767f8d325 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -40,7 +40,7 @@ For a commit to be verified by GitLab: account. - One of the emails in the GPG key must match a **verified** email address used by the committer in GitLab. This address will be part of the public key. - If you want to keep this address private, use the automatically generated + If you want to keep this address private, use the automatically generated [private commit email address](../../../profile/index.md#use-an-automatically-generated-private-commit-email) GitLab provides in your profile. - The committer's email address must match the verified email address from the @@ -54,17 +54,18 @@ started: 1. [Install GPG](https://www.gnupg.org/download/index.html) for your operating system. If your operating system has `gpg2` installed, replace `gpg` with `gpg2` in the following commands. -1. Generate the private/public key pair with the following command, which will - spawn a series of questions: +1. Generate the private/public key pair with the command appropriate for your version + of `gpg`. This command spawns a series of questions: ```shell + # Use this command for the default version of gpg, including + # Gpg4win on Windows, and most macOS versions: + gpg --gen-key + + # Use this command for versions of GPG later than 2.1.17: gpg --full-gen-key ``` - NOTE: - In some cases like Gpg4win on Windows and other macOS versions, the command - here may be `gpg --gen-key`. - 1. The first question is which algorithm can be used. Select the kind you want or press <kbd>Enter</kbd> to choose the default (RSA and RSA): @@ -200,7 +201,7 @@ key to use. Replace `30F2B65B9246B6CA` with your GPG key ID. -1. (Optional) If Git is using `gpg` and you get errors like `secret key not available` +1. Optional. If Git is using `gpg` and you get errors like `secret key not available` or `gpg: signing failed: secret key not available`, run the following command to change to `gpg2`: diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index bb1a55f6b2b..54e9470892c 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -248,9 +248,19 @@ When you [rename a user](../../profile/index.md#change-your-username), - The redirects are available as long as the original path is not claimed by another group, user, or project. -## Related links +## Related topics -- [GitLab Workflow VS Code extension](vscode.md) +- [GitLab Workflow VS Code extension](vscode.md). +- To lock files and prevent change conflicts, use [file locking](../file_lock.md). +- [Repository API](../../../api/repositories.md). +- [Find files](file_finder.md) in a repository. +- [Branches](branches/index.md). +- [File templates](web_editor.md#template-dropdowns). +- [Create a directory](web_editor.md#create-a-directory). +- [Start a merge request](web_editor.md#tips). +- [Find file history](git_history.md). +- [Identify changes by line (Git blame)](git_blame.md). +- [Use Jupyter notebooks with GitLab](jupyter_notebooks/index.md). ## Troubleshooting @@ -287,16 +297,3 @@ The same approach should also allow misidentified file types to be fixed. ``` `*.txt` files have an entry in the heuristics file. This example prevents parsing of these files. - -## Related topics - -- To lock files and prevent change conflicts, use [file locking](../file_lock.md). -- [Repository API](../../../api/repositories.md). -- [Find files](file_finder.md) in a repository. -- [Branches](branches/index.md). -- [File templates](web_editor.md#template-dropdowns). -- [Create a directory](web_editor.md#create-a-directory). -- [Start a merge request](web_editor.md#tips). -- [Find file history](git_history.md). -- [Identify changes by line (Git blame)](git_blame.md). -- [Use Jupyter notebooks with GitLab](jupyter_notebooks/index.md). diff --git a/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook_diff_v14_5.png b/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook_diff_v14_5.png Binary files differindex bc63322cd65..3dc940c23de 100644 --- a/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook_diff_v14_5.png +++ b/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook_diff_v14_5.png diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 8074f311e5f..ba105a970a7 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -175,10 +175,10 @@ request, you can create a new branch upfront.  1. Enter a new **Branch name**. -1. (Optional) Change the **Create from** field to choose which branch, tag, or +1. Optional. Change the **Create from** field to choose which branch, tag, or commit SHA this new branch originates from. This field autocompletes if you start typing an existing branch or tag. -1. Click **Create branch** to return to the file browser on this new branch. +1. To return to the file browser on this new branch, select **Create branch**.  @@ -201,10 +201,10 @@ SHA: 1. Give the tag a name such as `v1.0.0`. 1. Choose the branch or SHA from which you want to create this new tag. -1. (Optional) Add a message and release notes. The release notes section supports +1. Optional. Add a message and release notes. The release notes section supports Markdown format. -1. (Optional) Upload an attachment. -1. Click **Create tag**, and GitLab redirects you to the tag list page. +1. Optional. Upload an attachment. +1. Select **Create tag**. GitLab redirects you to the tag list page.  diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 2db7ae308bd..f9d9af3e672 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -290,7 +290,7 @@ To investigate why a commit shows as `Unverified`: 1. The verification status is stored in the database. To display the database record: ```ruby - pp X509CommitSignature.by_commit_sha(commit.sha);nil + pp CommitSignatures::X509CommitSignature.by_commit_sha(commit.sha);nil ``` If all the previous checks returned the correct values: diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 6ee23c91680..294e493dfe9 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -17,6 +17,10 @@ In 14.4, Requirements was moved under **Issues**. With requirements, you can set criteria to check your products against. They can be based on users, stakeholders, system, software, or anything else you find important to capture. +INFO: +Meet your compliance needs with requirements in GitLab. +[Try Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-project-requirements-docs). + A requirement is an artifact in GitLab which describes the specific behavior of your product. Requirements are long-lived and don't disappear unless manually cleared. @@ -134,7 +138,7 @@ You can also sort the requirements list by: > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) ability to specify individual requirements and their statuses in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2. -GitLab supports [requirements test reports](../../../ci/yaml/index.md#artifactsreportsrequirements) now. +GitLab supports [requirements test reports](../../../ci/yaml/artifacts_reports.md#artifactsreportsrequirements) now. You can add a job to your CI pipeline that, when triggered, marks all existing requirements as Satisfied (you may manually satisfy a requirement in the edit form [edit a requirement](#edit-a-requirement)). diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 4f8e068ca2d..072d685bde4 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -274,7 +274,7 @@ When configured, the custom suffix creates a new Service Desk email address, con For example, suppose the `mygroup/myproject` project Service Desk settings has the following configured: -- Project name suffix is set to `support`. +- Email address suffix is set to `support`. - Service Desk email address is configured to `contact+%{key}@example.com`. The Service Desk email address for this project is: `contact+mygroup-myproject-support@example.com`. @@ -289,6 +289,8 @@ In these issues, you can also see our friendly neighborhood [Support Bot](#suppo ### As an end user (issue creator) +> Support for additional email headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346600) in GitLab 14.6. +> In earlier versions, the Service Desk email address had to be in the "To" field. To create a Service Desk issue, an end user does not need to know anything about the GitLab instance. They just send an email to the address they are given, and receive an email back confirming receipt: @@ -304,6 +306,9 @@ are sent as emails: Any responses they send via email are displayed in the issue itself. +For information about headers used for treating email, see +[the incoming email documentation](../../administration/incoming_email.md#accepted-headers). + ### As a responder to the issue For responders to the issue, everything works just like other GitLab issues. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 74879dae2d6..da0336d01ff 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -44,8 +44,9 @@ Note the following: a maintainer or administrator role in the group where the exported project lives. - Project members with the [Owner role](../../permissions.md) are imported as Maintainers. - Imported users can be mapped by their public email on self-managed instances, if an administrative user (not an owner) does the import. - Additionally, the user must be an existing member of the namespace, or the user can be added as a -member of the project for contributions to be mapped. + The public email is not set by default. Users must [set it in their profiles](../../profile/index.md#set-your-public-email) + for mapping to work correctly. Additionally, the user must be an existing member of the namespace, + or the user can be added as a member of the project for contributions to be mapped. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues are owned by the importer. - For project migration imports performed over GitLab.com Groups, preserving author information is diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 5c4d4649240..c6cbd45a6ab 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -7,18 +7,18 @@ type: reference, index, howto # Project settings **(FREE)** -NOTE: -Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) -to access project settings. - The **Settings** page in GitLab provides a centralized home for your [project](../index.md) configuration options. To access it, go to your project's homepage -and, in the left navigation menu, clicking **Settings**. To reduce complexity, settings are -grouped by topic into sections. To display all settings in a section, click **Expand**. +and, in the left navigation menu, select **Settings**. To reduce complexity, settings are +grouped by topic into sections. To display all settings in a section, select **Expand**. In GitLab versions [13.10 and later](https://gitlab.com/groups/gitlab-org/-/epics/4842), GitLab displays a search box to help you find the settings you want to view. +NOTE: +Only users who have the [Maintainer role](../../permissions.md) for the project and administrators can +access project settings. + ## General settings Under a project's general settings, you can find everything concerning the @@ -315,7 +315,7 @@ Set up your project's merge request settings: - Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). - Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch). - Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). -- Configure [merge commit message template](../merge_requests/commit_templates.md). +- Configure [merge and squash commit message templates](../merge_requests/commit_templates.md). - Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. ### Service Desk @@ -449,17 +449,22 @@ To delete a project: This action deletes a project including all associated resources (issues, merge requests, and so on). -In [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) and later, on Premium or higher tiers, -group Owners can [configure](../../group/index.md#enable-delayed-project-removal) projects in a group -to be deleted after a delayed period. -When enabled, actual deletion happens after number of days -specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). - 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. +The default deletion behavior for projects was changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) +in GitLab 12.6, and then to [immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. + +#### Delayed project deletion **(PREMIUM)** + +Projects in a group (not a personal namespace) can be deleted after a delay period. Multiple settings can affect whether +delayed project deletion is enabled for a particular project: + +- Self-managed instance [settings](../../admin_area/settings/visibility_and_access_controls.md#default-delayed-project-deletion). + You can enable delayed project deletion as the default setting for new groups, and configure the number of days for the + delay. For GitLab.com, see the [GitLab.com settings](../../gitlab_com/index.md#delayed-project-deletion). +- Group [settings](../../group/index.md#enable-delayed-project-deletion) to enabled delayed project deletion for all + projects in the group. -#### Delete a project immediately **(PREMIUM)** +##### Delete a project immediately > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 85e412e7a41..44ece6cb172 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -12,111 +12,91 @@ type: reference, howto > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/342327) in GitLab 14.5. Default prefix added. -Project access tokens are similar to [personal access tokens](../../profile/personal_access_tokens.md) -except they are attached to a project rather than a user. They can be used to: +You can use a project access token to authenticate: -- Authenticate with the [GitLab API](../../../api/index.md#personalproject-access-tokens). -- Authenticate with Git using HTTP Basic Authentication. If you are asked for a username when - authenticating, you can use any non-empty value because only the token is needed. +- With the [GitLab API](../../../api/index.md#personalproject-access-tokens). +- With Git, when using HTTP Basic Authentication. -Project access tokens: +After you configure a project access token, you don't need a password when you authenticate. +Instead, you can enter any non-blank value. -- Expire on the date you define, at midnight UTC. -- Are supported for self-managed instances on Free tier and above. Free self-managed instances - should: - - Review their security and compliance policies with regards to +Project access tokens are similar to [personal access tokens](../../profile/personal_access_tokens.md), +except they are associated with a project rather than a user. + +You can use project access tokens: + +- On GitLab SaaS if you have the Premium license tier or higher. Personal access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). +- On self-managed instances of GitLab, with any license tier. If you have the Free tier: + - Review your security and compliance policies around [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups). - Consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to lower potential abuse. -- Are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/).) -For examples of how you can use a project access token to authenticate with the API, see the -[relevant section from our API Docs](../../../api/index.md#personalproject-access-tokens). +Project access tokens inherit the [default prefix setting](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) +configured for personal access tokens. -NOTE: -For GitLab.com and self-managed instances, the default prefix is `glpat-`. +## Create a project access token -## Creating a project access token +To create a project access token: -1. Log in to GitLab. -1. Navigate to the project you would like to create an access token for. -1. In the **Settings** menu choose **Access Tokens**. -1. Choose a name and optional expiry date for the token. -1. Choose a role for the token. -1. Choose the [desired scopes](#limiting-scopes-of-a-project-access-token). -1. Click the **Create project access token** button. -1. Save the project access token somewhere safe. Once you leave or refresh - the page, you don't have access to it again. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Access Tokens**. +1. Enter a name. +1. Optional. Enter an expiry date for the token. The token will expire on that date at midnight UTC. +1. Select a role for the token. +1. Select the [desired scopes](#scopes-for-a-project-access-token). +1. Select **Create project access token**. -## Project bot users +A project access token is displayed. Save the project access token somewhere safe. After you leave or refresh the page, you can't view it again. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. -> - [Excluded from license seat use](https://gitlab.com/gitlab-org/gitlab/-/issues/223695) in GitLab 13.5. +## Revoke a project access token -Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users) and do not count as licensed seats. +To revoke a project access token: -For each project access token created, a bot user is created and added to the project with -the [specified level permissions](../../permissions.md#project-members-permissions). - -For the bot: - -- The name is set to the name of the token. -- The username is set to `project_{project_id}_bot` for the first access token, such as `project_123_bot`. -- The email is set to `project{project_id}_bot@example.com`, for example `project123_bot@example.com`. -- For additional access tokens in the same project, the username is set to `project_{project_id}_bot{bot_count}`, for example `project_123_bot1`. -- For additional acess tokens in the same project, the email is set to `project{project_id}_bot{bot_count}@example.com`, for example `project123_bot1@example.com` - -API calls made with a project access token are associated with the corresponding bot user. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Access Tokens**. +1. Next to the project access token to revoke, select **Revoke**. -These bot users are included in a project's **Project information > Members** list but cannot be modified. Also, a bot -user cannot be added to any other project. +## Scopes for a project access token -When the project access token is [revoked](#revoking-a-project-access-token), the bot user is deleted -and all records are moved to a system-wide user with the username "Ghost User". For more -information, see [Associated Records](../../profile/account/delete_account.md#associated-records). +The scope determines the actions you can perform when you authenticate with a project access token. -## Revoking a project access token - -At any time, you can revoke any project access token by clicking the -respective **Revoke** button in **Settings > Access Tokens**. - -## Limiting scopes of a project access token - -Project access tokens can be created with one or more scopes that allow various -actions that a given token can perform. The available scopes are depicted in -the following table. - -| Scope | Description | -| ------------------ | ----------- | -| `api` | Grants complete read/write access to the scoped project API, 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. | +| Scope | Description | +|:-------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api` | Grants complete read and 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 the [Container Registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | +| `write_registry` | Allows write access (push) to the [Container Registry](../../packages/container_registry/index.md). | +| `read_repository` | Allows read access (pull) to the repository. | +| `write_repository` | Allows read and write access (pull and push) to the repository. | ## Enable or disable project access token creation > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287707) in GitLab 13.11. -You may enable or disable project access token creation for all projects in a group in **Group > Settings > General > Permissions, LFS, 2FA > Allow project access token creation**. -Even when creation is disabled, you can still use and revoke existing project access tokens. -This setting is available only on top-level groups. +To enable or disable project access token creation for all projects in a top-level group: -## Group access token workaround **(FREE SELF)** +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Permissions, LFS, 2FA**. +1. Under **Permissions**, turn on or off **Allow project access token creation**. -NOTE: -This section describes a workaround and is subject to change. +Even when creation is disabled, you can still use and revoke existing project access tokens. + +## Group access tokens **(FREE SELF)** -Group access tokens let you use a single token to: +With group access tokens, you can use a single token to: -- Perform actions at the group level. +- Perform actions for groups. - Manage the projects within the group. -- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate - with Git over HTTPS. +- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate with Git over HTTPS. + +NOTE: +You cannot use the UI to create a group access token. [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) +to add this functionality. This section describes a workaround. -We don't support group access tokens in the GitLab UI, though GitLab self-managed -administrators can create them using the [Rails console](../../../administration/operations/rails_console.md). +If you are an administrator of a self-managed GitLab instance, you can create a group access token in the +[Rails console](../../../administration/operations/rails_console.md). <div class="video-fallback"> For a demo of the group access token workaround, see <a href="https://www.youtube.com/watch?v=W2fg1P1xmU0">Demo: Group Level Access Tokens</a>. @@ -127,37 +107,83 @@ administrators can create them using the [Rails console](../../../administration ### Create a group access token -To create a group access token, run the following in a Rails console: +To create a group access token: -```ruby -admin = User.find(1) # group admin -group = Group.find(109) # the group you want to create a token for -bot = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot", email: "group_#{group.id}_bot@example.com", user_type: :project_bot }).execute # create the group bot user -# for further group access tokens, the username should be group_#{group.id}_bot#{bot_count}, e.g. group_109_bot2, and their email should be group_109_bot2@example.com -bot.confirm # confirm the bot -group.add_user(bot, :maintainer) # add the bot to the group at the desired access level -token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token') # give it a PAT -gtoken = token.token # get the token value -``` +1. Run the following commands in a [Rails console](../../../administration/operations/rails_console.md): + + ```ruby + # Set the GitLab administration user to use. If user ID 1 is not available or is not an adinistrator, use 'admin = User.admins.first' instead to select an admininistrator. + admin = User.find(1) + + # Set the group group you want to create a token for. For example, group with ID 109. + group = Group.find(109) + + # Create the group bot user. For further group access tokens, the username should be group_#{group.id}_bot#{bot_count}. For example, group_109_bot2 and email address group_109_bot2@example.com. + bot = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot", email: "group_#{group.id}_bot@example.com", user_type: :project_bot }).execute + + # Confirm the group bot. + bot.confirm + + # Add the bot to the group with the required role. + group.add_user(bot, :maintainer) -Test if the generated group access token works: + # Give the bot a personal access token. + token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token') -1. Pass the group access token in the `PRIVATE-TOKEN` header to GitLab REST APIs. For example: + # Get the token value. + gtoken = token.token + ``` - - [Create an epic](../../../api/epics.md#new-epic) on the group. - - [Create a project pipeline](../../../api/pipelines.md#create-a-new-pipeline) - in one of the group's projects. - - [Create an issue](../../../api/issues.md#new-issue) in one of the group's projects. +1. Test if the generated group access token works: -1. Use the group token to [clone a group's project](../../../gitlab-basics/start-using-git.md#clone-with-https) - using HTTPS. + 1. Use the group access token in the `PRIVATE-TOKEN` header with GitLab REST APIs. For example: + + - [Create an epic](../../../api/epics.md#new-epic) in the group. + - [Create a project pipeline](../../../api/pipelines.md#create-a-new-pipeline) in one of the group's projects. + - [Create an issue](../../../api/issues.md#new-issue) in one of the group's projects. + + 1. Use the group token to [clone a group's project](../../../gitlab-basics/start-using-git.md#clone-with-https) + using HTTPS. ### Revoke a group access token -To revoke a group access token, run the following in a Rails console: +To revoke a group access token, run the following command in a [Rails console](../../../administration/operations/rails_console.md): ```ruby bot = User.find_by(username: 'group_109_bot') # the owner of the token you want to revoke token = bot.personal_access_tokens.last # the token you want to revoke token.revoke! ``` + +## Project bot users + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. +> - [Excluded from license seat use](https://gitlab.com/gitlab-org/gitlab/-/issues/223695) in GitLab 13.5. + +Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users). +Each time you create a project access token, a bot user is created and added to the project. +These bot users do not count as licensed seats. + +The bot users have [permissions](../../permissions.md#project-members-permissions) that correspond with the +selected role and [scope](#scopes-for-a-project-access-token) of the project access token. + +- The name is set to the name of the token. +- The username is set to `project_{project_id}_bot` for the first access token. For example, `project_123_bot`. +- The email is set to `project{project_id}_bot@example.com`. For example, `project123_bot@example.com`. +- For additional access tokens in the same project, the username is set to `project_{project_id}_bot{bot_count}`. For + example, `project_123_bot1`. +- For additional access tokens in the same project, the email is set to `project{project_id}_bot{bot_count}@example.com`. + For example, `project123_bot1@example.com`. + +API calls made with a project access token are associated with the corresponding bot user. + +Bot users: + +- Are included in a project's member list but cannot be modified. +- Cannot be added to any other project. + +When the project access token is [revoked](#revoke-a-project-access-token): + +- The bot user is deleted. +- All records are moved to a system-wide user with the username `Ghost User`. For more information, see + [associated records](../../profile/account/delete_account.md#associated-records). diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 431250a817d..50b1a3a929d 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -72,11 +72,11 @@ First, set up the project. Once done, you can use the Static Site Editor to 1. To get started, create a new project from the [Static Site Editor - Middleman](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman) template. You can either [fork it](../repository/forking_workflow.md#creating-a-fork) - or [create a new project from a template](../working_with_projects.md#built-in-templates). + or [create a new project from a template](../working_with_projects.md#create-a-project-from-a-built-in-template). 1. Edit the [`data/config.yml`](#static-site-generator-configuration) configuration file to replace `<username>` and `<project-name>` with the proper values for your project's path. -1. (Optional) Edit the [`.gitlab/static-site-editor.yml`](#static-site-editor-configuration-file) file +1. Optional. Edit the [`.gitlab/static-site-editor.yml`](#static-site-editor-configuration-file) file to customize the behavior of the Static Site Editor. 1. When you submit your changes, GitLab triggers a CI/CD pipeline to deploy your project with GitLab Pages. 1. When the pipeline finishes, from your project's left-side menu, go to **Settings > Pages** to find the URL of your new website. @@ -96,15 +96,15 @@ After setting up your project, you can start editing content directly from the S To edit a file: 1. Visit the page you want to edit. -1. Click the **Edit this page** button. +1. Select **Edit this page**. 1. The file is opened in the Static Site Editor in **WYSIWYG** mode. If you wish to edit the raw Markdown instead, you can toggle the **Markdown** mode in the bottom-right corner. 1. When you're done, click **Submit changes...**. -1. (Optional) Adjust the default title and description of the merge request, to submit +1. Optional. Adjust the default title and description of the merge request, to submit with your changes. Alternatively, select a [merge request template](../../../user/project/description_templates.md#create-a-merge-request-template) from the dropdown menu and edit it accordingly. -1. Click **Submit changes**. +1. Select **Submit changes**. 1. A new merge request is automatically created and you can assign a colleague for review. ### Text @@ -123,11 +123,11 @@ The Static Site Editors supports Markdown files (`.md`, `.md.erb`) for editing t You can upload image files via the WYSIWYG editor directly to the repository to default upload directory `source/images`. To do so: -1. Click the image icon (**{doc-image}**). -1. Choose the **Upload file** tab. -1. Click **Choose file** to select a file from your computer. -1. Optional: add a description to the image for SEO and accessibility ([ALT text](https://moz.com/learn/seo/alt-text)). -1. Click **Insert image**. +1. Select the image icon (**{doc-image}**). +1. Select the **Upload file** tab. +1. To select a file from your computer, select **Choose file**. +1. Optional. Add a description to the image for SEO and accessibility ([ALT text](https://moz.com/learn/seo/alt-text)). +1. Select **Insert image**. The selected file can be any supported image file (`.png`, `.jpg`, `.jpeg`, `.gif`). The editor renders thumbnail previews so you can verify the correct image is included and there aren't any references to @@ -137,11 +137,11 @@ missing images. You can also link to an image if you'd like: -1. Click the image icon (**{doc-image}**). -1. Choose the **Link to an image** tab. +1. Select the image icon (**{doc-image}**). +1. Select the **Link to an image** tab. 1. Add the link to the image into the **Image URL** field (use the full path; relative paths are not supported yet). -1. Optional: add a description to the image for SEO and accessibility ([ALT text](https://moz.com/learn/seo/alt-text)). -1. Click **Insert image**. +1. Optional. Add a description to the image for SEO and accessibility ([ALT text](https://moz.com/learn/seo/alt-text)). +1. Select **Insert image**. The link can reference images already hosted in your project, an asset hosted externally on a content delivery network, or any other external URL. The editor renders thumbnail previews diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 8902bdc21c4..b41ea30bfef 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -123,7 +123,7 @@ To do so: With this option enabled, `75h` is displayed instead of `1w 4d 3h`. -## Related links +## Related topics - [Time tracking solutions page](https://about.gitlab.com/solutions/time-tracking/) - Time tracking GraphQL references: diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index d75a180492e..40c9ae8bd59 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -456,7 +456,7 @@ when: - <kbd>Control</kbd> + <kbd>S</kbd> (or <kbd>Command</kbd> + <kbd>S</kbd> on Mac) is pressed while editing a file. -- Anything outside the file editor is clicked after editing a file. +- You select any area outside the file editor after editing a file. - A file or folder is created, deleted, or renamed. ### Limitations diff --git a/doc/user/project/wiki/img/content_editor_v14.0.png b/doc/user/project/wiki/img/content_editor_v14.0.png Binary files differdeleted file mode 100644 index b44a633073d..00000000000 --- a/doc/user/project/wiki/img/content_editor_v14.0.png +++ /dev/null diff --git a/doc/user/project/wiki/img/content_editor_v14.6.png b/doc/user/project/wiki/img/content_editor_v14.6.png Binary files differnew file mode 100644 index 00000000000..55fca0ace1e --- /dev/null +++ b/doc/user/project/wiki/img/content_editor_v14.6.png diff --git a/doc/user/project/wiki/img/use_new_editor_button_v14.0.png b/doc/user/project/wiki/img/use_new_editor_button_v14.0.png Binary files differdeleted file mode 100644 index d9a5cf83302..00000000000 --- a/doc/user/project/wiki/img/use_new_editor_button_v14.0.png +++ /dev/null diff --git a/doc/user/project/wiki/img/use_new_editor_button_v14.6.png b/doc/user/project/wiki/img/use_new_editor_button_v14.6.png Binary files differnew file mode 100644 index 00000000000..078fed8a1e9 --- /dev/null +++ b/doc/user/project/wiki/img/use_new_editor_button_v14.6.png diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 5d2a0530f68..9f1670d3f4c 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -87,7 +87,7 @@ Users with the [Developer role](../../permissions.md) can create new wiki pages: [special characters](#special-characters-in-page-titles) for subdirectories and formatting, and have [length restrictions](#length-restrictions-for-file-and-directory-names). 1. Add content to your wiki page. -1. (Optional) Attach a file, and GitLab stores it according to your installed version of GitLab: +1. Optional. Attach a file, and GitLab stores it according to your installed version of GitLab: - *Files added in [GitLab 11.3 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475):* Files are stored in the wiki's Git repository. - *Files added GitLab 11.2 and earlier:* Files are stored in GitLab itself. To add @@ -236,7 +236,7 @@ GitLab tracks wiki creation, deletion, and update events. These events are displ - [User profile](../../profile/index.md#access-your-user-profile). - Activity pages, depending on the type of wiki: - [Group activity](../../group/index.md#view-group-activity). - - [Project activity](../working_with_projects.md#project-activity). + - [Project activity](../working_with_projects.md#view-project-activity). Commits to wikis are not counted in [repository analytics](../../analytics/repository_analytics.md). @@ -290,7 +290,7 @@ To add a link to an external wiki from a project's left sidebar: 1. On the left sidebar, select **Settings > Integrations**. 1. Select **External wiki**. 1. Add the URL to your external wiki. -1. (Optional) Select **Test settings** to verify the connection. +1. Optional. To verify the connection, select **Test settings**. 1. Select **Save changes**. You can now see the **External wiki** option from your project's @@ -339,27 +339,24 @@ experience in the Wiki. To opt in for the new editor: 1. Create a new wiki page, or edit an existing one. 1. Ensure the wiki page uses the Markdown format. Other formats are not yet supported. -1. Below the **Format** select box, select **Use the new editor**: +1. Above the content field, select **Edit rich text**: -  +  ### Use the Content Editor 1. [Create](#create-a-new-wiki-page) a new wiki page, or [edit](#edit-a-wiki-page) an existing one. 1. Select **Markdown** as your format. -1. Below the **Format** select box, select **Use new editor**. +1. Above **Content**, select **Edit rich text**. 1. Customize your page's content using the various formatting options available in the content editor. 1. Select **Create page** for a new page, or **Save changes** for an existing page: -  +  ### Switch back to the old editor 1. *If you're editing the page in the content editor,* scroll to **Content**. -1. Select **Switch me back to the classic editor**. -1. Select **Switch to classic editor** in the confirmation popup to confirm. - -When you switch back to the old editor, any unsaved changes are lost. +1. Select **Edit source**. ### GitLab Flavored Markdown support diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 3c82e544e26..b5b3f2d2085 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -4,35 +4,59 @@ group: Workspace info: "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" --- -# Working with projects **(FREE)** +# Manage projects **(FREE)** Most work in GitLab is done in a [project](../../user/project/index.md). Files and code are saved in projects, and most features are in the scope of projects. -## Explore projects +## View projects -You can explore other popular projects available on GitLab. To explore projects: +To explore projects: 1. On the top bar, select **Menu > Projects**. 1. Select **Explore projects**. -GitLab displays a list of projects, sorted by last updated date. To view -projects with the most [stars](#star-a-project), click **Most stars**. To view -projects with the largest number of comments in the past month, click **Trending**. +The **Projects** page shows a list of projects, sorted by last updated date. + +- To view projects with the most [stars](#star-a-project), select **Most stars**. +- To view projects with the largest number of comments in the past month, select **Trending**. NOTE: -By default, `/explore` is visible to unauthenticated users. However, if the +The **Explore projects** tab is visible to unauthenticated users unless the [**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) -is restricted, `/explore` is visible only to signed-in users. +is restricted. Then the tab is visible only to signed-in users. + +### Who can view the **Projects** page + +When you select a project, the project landing page shows the project contents. + +For public projects, and members of internal and private projects +with [permissions to view the project's code](../permissions.md#project-members-permissions), +the project landing page shows: + +- A [`README` or index file](repository/index.md#readme-and-index-files). +- A list of directories in the project's repository. + +For users without permission to view the project's code, the landing page shows: + +- The wiki homepage. +- The list of issues in the project. + +### Access a project page with the project ID + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. + +To access a project from the GitLab UI using the project ID, +visit the `/projects/:id` URL in your browser or other tool accessing the project. ## Explore topics -You can explore popular project topics available on GitLab. To explore project topics: +To explore project topics: 1. On the top bar, select **Menu > Projects**. 1. Select **Explore topics**. -GitLab displays a list of topics sorted by the number of associated projects. +The **Projects** page shows list of topics sorted by the number of associated projects. To view projects associated with a topic, select a topic from the list. You can assign topics to a project on the [Project Settings page](settings/index.md#topics). @@ -44,290 +68,280 @@ If you're an instance administrator, you can administer all project topics from To create a project in GitLab: -1. In your dashboard, select **New project** or use the **New...** **{plus-square}** icon -on the top bar. The **New project** page opens. +1. On the top bar, select **Menu > Project**. +1. Select **Create new project**. 1. On the **New project** page, choose if you want to: - - Create a [blank project](#blank-projects). - - Create a project using one of the available [project templates](#project-templates). - - [Import a project](../../user/project/import/index.md) from a different repository, - if enabled on your GitLab instance. Contact your GitLab administrator if this is unavailable. - - Run [CI/CD pipelines for external repositories](../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** + - Create a [blank project](#create-a-blank-project). + - Create a project from a: + - [built-in template](#create-a-project-from-a-built-in-template). + - [custom template](#create-a-project-from-a-custom-template). + - [HIPAA audit protocol template](#create-a-project-from-the-hipaa-audit-protocol-template). + - [Import a project](../../user/project/import/index.md) + from a different repository. Contact your GitLab administrator if this option is not available. + - [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). NOTE: For a list of words that can't be used as project names see -[Reserved project and group names](../../user/reserved_names.md). - -### Blank projects - -To create a new blank project on the **New project** page: - -1. Click **Create blank project** -1. Provide the following information: - - The name of your project in the **Project name** field. You can't use - special characters, but you can use spaces, hyphens, underscores, or even - emoji. When adding the name, the **Project slug** auto populates. - The slug is what the GitLab instance uses as the URL path to the project. - If you want a different slug, input the project name first, - then change the slug after. - - The path to your project in the **Project slug** field. This is the URL - path for your project that the GitLab instance uses. If the - **Project name** is blank, it auto populates when you fill in - the **Project slug**. - - The **Project description (optional)** field enables you to enter a - description for your project's dashboard, which helps others - understand what your project is about. Though it's not required, it's a good - idea to fill this in. - - Changing the **Visibility Level** modifies the project's - [viewing and access rights](../../public_access/public_access.md) for users. - - Selecting the **Initialize repository with a README** option creates a - README file so that the Git repository is initialized, has a default branch, and - can be cloned. -1. Click **Create project**. - -### Project templates - -Project templates can pre-populate a new project with the necessary files to get you -started quickly. - -There are two main types of project templates: - -- [Built-in templates](#built-in-templates), sourced from the following groups: - - [`project-templates`](https://gitlab.com/gitlab-org/project-templates) - - [`pages`](https://gitlab.com/pages) -- [Custom project templates](#custom-project-templates), for custom templates - configured by GitLab administrators and users. - -#### Built-in templates - -Built-in templates are project templates that are: - -- Developed and maintained in the [`project-templates`](https://gitlab.com/gitlab-org/project-templates) - and [`pages`](https://gitlab.com/pages) groups. -- Released with GitLab. -- Anyone can contribute a built-in template by following [these steps](https://about.gitlab.com/community/contribute/project-templates/). - -To use a built-in template on the **New project** page: - -1. Click **Create from template** +[reserved project and group names](../../user/reserved_names.md). + +## Create a blank project + +To create a blank project: + +1. On the top bar, select **Menu > Project**. +1. Select **Create new project**. +1. Select **Create blank project**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, + underscores, and emoji. You cannot use special characters. After you enter the name, + the **Project slug** populates. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - In the **Project description (optional)** field, enter the description of your project's dashboard. + - To modify the project's [viewing and access rights](../../public_access/public_access.md) for + users, change the **Visibility Level**. + - To create README file so that the Git repository is initialized, has a default branch, and + can be cloned, select **Initialize repository with a README**. + - To analyze the source code in the project for known security vulnerabilities, + select **Enable Static Application Security Testing (SAST)**. +1. Select **Create project**. + +## Create a project from a built-in template + +A built-in project template populates a new project with files to get you started. +Built-in templates are sourced from the following groups: + +- [`project-templates`](https://gitlab.com/gitlab-org/project-templates) +- [`pages`](https://gitlab.com/pages) + +Anyone can contribute a built-in template by following [these steps](https://about.gitlab.com/community/contribute/project-templates/). + +To create a project from a built-in template: + +1. On the top bar, select **Menu > Project**. +1. Select **Create new project**. +1. Select **Create from template**. 1. Select the **Built-in** tab. -1. From the list of available built-in templates, click the: - - **Preview** button to look at the template source itself. - - **Use template** button to start creating the project. -1. Finish creating the project by filling out the project's details. The process is - the same as creating a [blank project](#blank-projects). +1. From the list of templates: + - To view a preview of the template, select **Preview**. + - To use a template for the project, select **Use template**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, + underscores, and emoji. You cannot use special characters. After you enter the name, + the **Project slug** populates. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - In the **Project description (optional)** field, enter the description of your project's dashboard. + - To modify the project's [viewing and access rights](../../public_access/public_access.md) for users, + change the **Visibility Level**. +1. Select **Create project**. + +## Create a project from a custom template **(PREMIUM)** -##### Enterprise templates **(ULTIMATE)** - -GitLab is developing Enterprise templates to help you streamline audit management with selected regulatory standards. These templates automatically import issues that correspond to each regulatory requirement. - -To create a new project with an Enterprise template, on the **New project** page: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. -1. Click **Create from template** +Custom project templates are available at: + +- The [instance-level](../../user/admin_area/custom_project_templates.md) +- The [group-level](../../user/group/custom_project_templates.md) + +1. On the top bar, select **Menu > Project**. +1. Select **Create new project**. +1. Select **Create from template**. +1. Select the **Instance** or **Group** tab. +1. From the list of templates: + - To view a preview of the template, select **Preview**. + - To use a template for the project, select **Use template**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, + underscores, and emoji. You cannot use special characters. After you enter the name, + the **Project slug** populates. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - The description of your project's dashboard in the **Project description (optional)** field. + - To modify the project's [viewing and access rights](../../public_access/public_access.md) for users, + change the **Visibility Level**. +1. Select **Create project**. + +## Create a project from the HIPAA Audit Protocol template **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10 + +The HIPAA Audit Protocol template contains issues for audit inquiries in the +HIPAA Audit Protocol published by the U.S Department of Health and Human Services. + +To create a project from the HIPAA Audit Protocol template: + +1. On the top bar, select **Menu > Project**. +1. Select **Create new project**. +1. Select **Create from template**. 1. Select the **Built-in** tab. -1. From the list of available built-in Enterprise templates, click the: - - **Preview** button to look at the template source itself. - - **Use template** button to start creating the project. -1. Finish creating the project by filling out the project's details. The process is the same as creating a [blank project](#blank-projects). +1. Locate the **HIPAA Audit Protocol** template: + - To view a preview of the template, select **Preview**. + - To use the template for the project, select **Use template**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, + underscores, and emoji. You cannot use special characters. After you enter the name, + the **Project slug** populates. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - In the **Project description (optional)** field, enter the description of your project's dashboard. + - To modify the project's [viewing and access rights](../../public_access/public_access.md) for users, + change the **Visibility Level**. +1. Select **Create project**. + +## Push to create a new project -Available Enterprise templates include: +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. -- HIPAA Audit Protocol template ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10) +Use `git push` to push a local project repository to GitLab. After you push a repository, +GitLab creates your project in your chosen namespace. -NOTE: -You can improve the existing built-in templates or contribute new ones in the -[`project-templates`](https://gitlab.com/gitlab-org/project-templates) and -[`pages`](https://gitlab.com/pages) groups by following [these steps](https://gitlab.com/gitlab-org/project-templates/contributing). +You cannot use `git push` to create projects with project paths that: -##### Custom project templates **(PREMIUM)** +- Have previously been used. +- Have been [renamed](settings/index.md#renaming-a-repository). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. +Previously used project paths have a redirect. The redirect causes push attempts to redirect requests +to the renamed project location, instead of creating a new project. To create a new project for a previously +used or renamed project, use the [UI](#create-a-project) or the [Projects API](../../api/projects.md#create-project). -Creating new projects based on custom project templates is a convenient option for -quickly starting projects. +Prerequisites: -Custom projects are available at the [instance-level](../../user/admin_area/custom_project_templates.md) -from the **Instance** tab, or at the [group-level](../../user/group/custom_project_templates.md) -from the **Group** tab, on the **Create from template** page. +- To push with SSH, you must have [an SSH key](../../ssh/index.md) that is +[added to your GitLab account](../../ssh/index.md#add-an-ssh-key-to-your-gitlab-account). +- You must have permission to add new projects to a namespace. To check if you have permission: -To use a custom project template on the **New project** page: + 1. On the top bar, select **Menu > Project**. + 1. Select **Groups**. + 1. Select a group. + 1. Confirm that **New project** is visible in the upper right + corner. Contact your GitLab + administrator if you require permission. -1. Click **Create from template** -1. Select the **Instance** tab or the **Group** tab. -1. From the list of available custom templates, click the: - - **Preview** button to look at the template source itself. - - **Use template** button to start creating the project. -1. Finish creating the project by filling out the project's details. The process is - the same as creating a [blank project](#blank-projects). +To push your repository and create a project: -## Push to create a new project +1. Push with SSH or HTTPS: + - To push with SSH: -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. + ```shell + git push --set-upstream git@gitlab.example.com:namespace/myproject.git master + ``` -When you create a new repository locally, you don't have to sign in to the GitLab -interface to create a project and -[clone its repository](../../gitlab-basics/start-using-git.md#clone-a-repository). -You can directly push your new repository to GitLab, which creates your new project -without leaving your terminal. - -To push a new project: - -1. Identify the [namespace](../group/index.md#namespaces) you want to add the new - project to, as you need this information in a future step. To determine if you have - permission to create new projects in a namespace, view the group's page in a - web browser and confirm the page displays a **New project** button. - - NOTE: - As project creation permissions can have many factors, contact your - GitLab administrator if you're unsure. - -1. If you want to push using SSH, ensure you have [created a SSH key](../../ssh/index.md) and - [added it to your GitLab account](../../ssh/index.md#add-an-ssh-key-to-your-gitlab-account). -1. Push with one of the following methods. Replace `gitlab.example.com` with the - domain name of the machine that hosts your Git repository, `namespace` with the name of - your namespace, and `myproject` with the name of your new project: - - To push with SSH: `git push --set-upstream git@gitlab.example.com:namespace/myproject.git master` - - To push with HTTPS: `git push --set-upstream https://gitlab.example.com/namespace/myproject.git master` - Optional: to export existing repository tags, append the `--tags` flag to your `git push` command. -1. When the push completes, GitLab displays a message: - - ```plaintext - remote: The private project namespace/myproject was created. - ``` + - To push with HTTPS: -1. (Optional) To configure the remote, alter the command - `git remote add origin https://gitlab.example.com/namespace/myproject.git` - to match your namespace and project names. + ```shell + git push --set-upstream https://gitlab.example.com/namespace/myproject.git master + ``` -You can view your new project at `https://gitlab.example.com/namespace/myproject`. -Your project's visibility is set to **Private** by default, but you can change it -in your [project's settings](../../public_access/public_access.md#change-project-visibility)). + - For `gitlab.example.com`, use the domain name of the machine that hosts your Git repository. + - For `namespace`, use the name of your [namespace](../group/index.md#namespaces). + - For `myproject`, use the name of your project. + - Optional. To export existing repository tags, append the `--tags` flag to your `git push` command. +1. Optional. To configure the remote: -This feature does not work for project paths that have previously been in use and -[renamed](settings/index.md#renaming-a-repository). A redirect exists over the previous project path -that causes push attempts to redirect requests to the renamed project location, instead of creating -a new project. To create a new project, use the [Web UI](#create-a-project) or the -[Projects API](../../api/projects.md#create-project). + ```shell + git remote add origin https://gitlab.example.com/namespace/myproject.git + ``` -## Fork a project +When the push completes, GitLab displays the message: -A fork is a copy of an original repository that you put in another namespace -where you can experiment and apply changes that you can later decide whether or -not to share, without affecting the original project. +```shell +remote: The private project namespace/myproject was created. +``` -It takes just a few steps to [fork a project in GitLab](repository/forking_workflow.md#creating-a-fork). +To view your new project, go to `https://gitlab.example.com/namespace/myproject`. +Your project's visibility is set to **Private** by default. To change project visibility, adjust your +[project's settings](../../public_access/public_access.md#change-project-visibility). ## Star a project -You can star a project to make it easier to find projects you frequently use. -The number of stars a project has can indicate its popularity. +You can add a star to projects you use frequently to make them easier to find. -To star a project: +To add a star to a project: -1. Go to the home page of the project you want to star. -1. In the upper right corner of the page, click **Star**. +1. On the top bar, select **Menu > Project**. +1. Select **Your projects** or **Explore projects**. +1. Select a project. +1. In the upper right corner of the page, select **Star**. -To view your starred projects: +## View starred projects -1. On the top bar, select **Menu > Projects**. -1. Select **Starred Projects**. +1. On the top bar, select **Menu > Project**. +1. Select **Starred projects**. 1. GitLab displays information about your starred projects, including: - - Project description, including name, description, and icon - - Number of times this project has been starred - - Number of times this project has been forked - - Number of open merge requests - - Number of open issues + - Project description, including name, description, and icon. + - Number of times this project has been starred. + - Number of times this project has been forked. + - Number of open merge requests. + - Number of open issues. ## Delete a project -To delete a project, first navigate to the home page for that project. +After you delete a project, projects in personal namespaces are deleted immediately. To delay deletion of projects in a group +you can [enable delayed project removal](../group/index.md#enable-delayed-project-deletion). -1. Navigate to **Settings > General**. +To delete a project: + +1. On the top bar, select **Menu > Project**. +1. Select **Your projects** or **Explore projects**. +1. Select a project. +1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. Scroll down to the **Delete project** section. -1. Click **Delete project** -1. Confirm this action by typing in the expected text. +1. Select **Delete project** +1. Confirm this action by completing the field. -Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects in a group, please see [Enable delayed project removal](../group/index.md#enable-delayed-project-removal). +## View project activity -## Project settings +To view the activity of a project: -Set the project's visibility level and the access levels to its various pages -and perform actions like archiving, renaming or transferring a project. +1. On the top bar, select **Menu > Project**. +1. Select **Your projects** or **Explore projects**. +1. Select a project. +1. On the left sidebar, select **Project information > Activity**. +1. Select a tab to view the type of project activity. -Read through the documentation on [project settings](settings/index.md). +## Leave a project -## Project activity +If you leave a project you are no longer a project +member and cannot contribute. -To view the activity of a project: +To leave a project: -1. On the left sidebar, select **Project information > Activity**. -1. Select a tab to view **All** the activity, or to filter it by any of these criteria: - - **Push events** - - **Merge events** - - **Issue events** - - **Comments** - - **Team** - - **Wiki** - -### Leave a project - -**Leave project** only displays on the project's dashboard -when a project is part of a group (under a -[group namespace](../group/index.md#namespaces)). -If you choose to leave a project you are no longer a project -member, and cannot contribute. - -## Use your project as a Go package - -Any project can be used as a Go package. GitLab responds correctly to `go get` -and `godoc.org` discovery requests, including the -[`go-import`](https://golang.org/cmd/go/#hdr-Remote_import_paths) and -[`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) meta tags. - -Private projects, including projects in subgroups, can be used as a Go package, -but may require configuration to work correctly. GitLab responds correctly -to `go get` discovery requests for projects that *are not* in subgroups, -regardless of authentication or authorization. -[Authentication](#authenticate-go-requests) is required to use a private project -in a subgroup as a Go package. Otherwise, GitLab truncates the path for -private projects in subgroups to the first two segments, causing `go get` to -fail. - -GitLab implements its own Go proxy. This feature must be enabled by an -administrator and requires additional configuration. See [GitLab Go -Proxy](../packages/go_proxy/index.md). - -### Disable Go module features for private projects - -In Go 1.12 and later, Go queries module proxies and checksum databases in the -process of [fetching a -module](../../development/go_guide/dependencies.md#fetching). This can be -selectively disabled with `GOPRIVATE` (disable both), -[`GONOPROXY`](../../development/go_guide/dependencies.md#proxies) (disable proxy -queries), and [`GONOSUMDB`](../../development/go_guide/dependencies.md#fetching) -(disable checksum queries). - -`GOPRIVATE`, `GONOPROXY`, and `GONOSUMDB` are comma-separated lists of Go -modules and Go module prefixes. For example, -`GOPRIVATE=gitlab.example.com/my/private/project` disables queries for that -one project, but `GOPRIVATE=gitlab.example.com` disables queries for *all* -projects on GitLab.com. Go does not query module proxies if the module name or a -prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go does not query checksum -databases if the module name or a prefix of it appears in `GONOPRIVATE` or -`GONOSUMDB`. - -### Authenticate Go requests - -To authenticate requests to private projects made by Go, use a [`.netrc` -file](https://everything.curl.dev/usingcurl/netrc) and a [personal access -token](../profile/personal_access_tokens.md) in the password field. **This only -works if your GitLab instance can be accessed with HTTPS.** The `go` command -does not transmit credentials over insecure connections. This authenticates -all HTTPS requests made directly by Go, but does not authenticate requests made -through Git. +1. On the top bar, select **Menu > Project**. +1. Select **Your projects** or **Explore projects**. +1. Select a project. +1. Select **Leave project**. The **Leave project** option only displays +on the project dashboard when a project is part of a group under a +[group namespace](../group/index.md#namespaces). -For example: +## Use a project as a Go package + +Prerequisites: + +- Contact your administrator to enable the [GitLab Go Proxy](../packages/go_proxy/index.md). +- To use a private project in a subgroup as a Go package, you must [authenticate Go requests](#authenticate-go-requests-to-private-projects). Go requests that are not authenticated cause +`go get` to fail. You don't need to authenticate Go requests for projects that are not in subgroups. + +To use a project as a Go package, use the `go get` and `godoc.org` discovery requests. You can use the meta tags: + +- [`go-import`](https://pkg.go.dev/cmd/go#hdr-Remote_import_paths) +- [`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) + +### Authenticate Go requests to private projects + +Prerequisites: + +- Your GitLab instance must be accessible with HTTPS. +- You must have a [personal access token](../profile/personal_access_tokens.md). + +To authenticate Go requests, create a [`.netrc`](https://everything.curl.dev/usingcurl/netrc) file with the following information: ```plaintext machine gitlab.example.com @@ -335,95 +349,110 @@ login <gitlab_user_name> password <personal_access_token> ``` -NOTE: On Windows, Go reads `~/_netrc` instead of `~/.netrc`. -### Authenticate Git fetches +The `go` command does not transmit credentials over insecure connections. It authenticates +HTTPS requests made by Go, but does not authenticate requests made +through Git. -If a module cannot be fetched from a proxy, Go falls back to using Git (for -GitLab projects). Git uses `.netrc` to authenticate requests. You can also -configure Git to either: +### Authenticate Git requests -- Embed specific credentials in the request URL. -- Use SSH instead of HTTPS, as Go always uses HTTPS to fetch Git repositories. +If Go cannot fetch a module from a proxy, it uses Git. Git uses a `.netrc` file to authenticate requests, but you can +configure other authentication methods. -```shell -# Embed credentials in any request to GitLab.com: -git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" +Configure Git to either: -# Use SSH instead of HTTPS: -git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" -``` +- Embed credentials in the request URL: -### Fetch Go modules from Geo secondary sites + ```shell + git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" + ``` + +- Use SSH instead of HTTPS: + + ```shell + git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" + ``` + +### Disable Go module fetching for private projects + +To [fetch modules or packages](../../development/go_guide/dependencies.md#fetching), Go uses +the [environment variables](../../development/go_guide/dependencies.md#proxies): -As Go modules are stored in Git repositories, you can use the [Geo](../../administration/geo/index.md) -feature that allows Git repositories to be accessed on the secondary Geo servers. +- `GOPRIVATE` +- `GONOPROXY` +- `GONOSUMDB` -In the following examples, the primary's site domain name is `gitlab.example.com`, -and the secondary's is `gitlab-secondary.example.com`. +To disable fetching: -`go get` will initially generate some HTTP traffic to the primary, but when the module -download commences, the `insteadOf` configuration sends the traffic to the secondary. +1. Disable `GOPRIVATE`: + - To disable queries for one project, disable `GOPRIVATE=gitlab.example.com/my/private/project`. + - To disable queries for all projects on GitLab.com, disable `GOPRIVATE=gitlab.example.com`. +1. Disable proxy queries in `GONOPROXY`. +1. Disable checksum queries in `GONOSUMDB`. -#### Use SSH to access the Geo secondary +- If the module name or its prefix is in `GOPRIVATE` or `GONOPROXY`, Go does not query module +proxies. +- If the module name or its prefix is in `GONOPRIVATE` or `GONOSUMDB`, Go does not query +Checksum databases. -To fetch Go modules from the secondary using SSH: +### Fetch Go modules from Geo secondary sites + +Use [Geo](../../administration/geo/index.md) to access Git repositories that contain Go modules +on secondary Geo servers. + +You can use SSH or HTTP to access the Geo secondary server. + +#### Use SSH to access the Geo secondary server + +To access the Geo secondary server with SSH: 1. Reconfigure Git on the client to send traffic for the primary to the secondary: - ```plaintext + ```shell git config --global url."git@gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" git config --global url."git@gitlab-secondary.example.com".insteadOf "http://gitlab.example.com" ``` -1. Ensure the client is set up for SSH access to GitLab repositories. This can be tested on the primary, - and GitLab will replicate the public key to the secondary. + - For `gitlab.example.com`, use the primary site domain name. + - For `gitlab-secondary.example.com`, use the secondary site domain name. + +1. Ensure the client is set up for SSH access to GitLab repositories. You can test this on the primary, + and GitLab replicates the public key to the secondary. + +The `go get` request generates HTTP traffic to the primary Geo server. When the module +download starts, the `insteadOf` configuration sends the traffic to the secondary Geo server. #### Use HTTP to access the Geo secondary -Using HTTP to fetch Go modules does not work with CI/CD job tokens, only with -persistent access tokens that are replicated to the secondary. +You must use persistent access tokens that replicate to the secondary server. You cannot use +CI/CD job tokens to fetch Go modules with HTTP. -To fetch Go modules from the secondary using HTTP: +To access the Geo secondary server with HTTP: -1. Put in place a Git `insteadOf` redirect on the client: +1. Add a Git `insteadOf` redirect on the client: - ```plaintext + ```shell git config --global url."https://gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" ``` + - For `gitlab.example.com`, use the primary site domain name. + - For `gitlab-secondary.example.com`, use the secondary site domain name. + 1. Generate a [personal access token](../profile/personal_access_tokens.md) and - provide those credentials in the client's `~/.netrc` file: + add the credentials in the client's `~/.netrc` file: - ```plaintext + ```shell machine gitlab.example.com login USERNAME password TOKEN machine gitlab-secondary.example.com login USERNAME password TOKEN ``` -## Access project page with project ID +The `go get` request generates HTTP traffic to the primary Geo server. When the module +download starts, the `insteadOf` configuration sends the traffic to the secondary Geo server. -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. +## Related topics -To quickly access a project from the GitLab UI using the project ID, -visit the `/projects/:id` URL in your browser or other tool accessing the project. - -## Project's landing page - -The project's landing page shows different information depending on -the project's visibility settings and user permissions. - -For public projects, and to members of internal and private projects -with [permissions to view the project's code](../permissions.md#project-members-permissions): - -- The content of a - [`README` or an index file](repository/index.md#readme-and-index-files) - is displayed (if any), followed by the list of directories in the - project's repository. -- If the project doesn't contain either of these files, the - visitor sees the list of files and directories of the repository. - -For users without permissions to view the project's code, GitLab displays: - -- The wiki homepage, if any. -- The list of issues in the project. +- [Import a project](../../user/project/import/index.md). +- [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). +- [Fork a project](repository/forking_workflow.md#creating-a-fork). +- [Adjust project visibility and access levels](settings/index.md#sharing-and-permissions). |
