diff options
Diffstat (limited to 'doc/user/project')
224 files changed, 4045 insertions, 3179 deletions
diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 0ea1a80bc54..26708dece50 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Organization +stage: Data Stores +group: Tenant Scale info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -62,7 +62,7 @@ You can access a test coverage report badge image by using the following link: https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg ``` -You can define the regular expression for the [coverage report](../../ci/pipelines/settings.md#merge-request-test-coverage-results) +You can define the regular expression for the [coverage report](../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) that each job log is matched against. This means that each job in the pipeline can have the test coverage percentage value defined. @@ -107,7 +107,7 @@ If there is no release, it shows `none`. You can access a latest release badge image by using the following link: ```plaintext -https://gitlab.example.com/<namespace>/<project>/badges/<branch>/release.svg +https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg ``` By default, the badge fetches the release sorted using the [`released_at`](../../api/releases/index.md#create-a-release) @@ -117,6 +117,10 @@ time with the `?order_by` query parameter. https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg?order_by=release_at ``` +You can change the width of the release name field by using the `value_width` parameter ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113615) in GitLab 15.10). +The value must be between 1 and 200, and the default value is 54. +If you set an out of range value, GitLab automatically adjusts it to the default value. + ## Project badges Badges can be added to a project by Maintainers or Owners, and are visible on the project's overview page. @@ -275,7 +279,7 @@ To add a new badge with a custom image to a group or project: 1. Select **Add badge**. To learn how to use custom images generated through a pipeline, see the documentation on -[accessing the latest job artifacts by URL](../../ci/pipelines/job_artifacts.md#access-the-latest-job-artifacts). +[accessing the latest job artifacts by URL](../../ci/jobs/job_artifacts.md#from-a-url). ## Placeholders diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 95f38c7e354..8ea762777ac 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -4,18 +4,16 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Canary Deployments **(FREE)** +# Canary deployments **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in GitLab 9.1. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) from GitLab Premium to GitLab Free in 13.8. -A popular [Continuous Deployment](https://en.wikipedia.org/wiki/Continuous_deployment) +Canary deployments are a popular [continuous deployment](https://en.wikipedia.org/wiki/Continuous_deployment) strategy, where a small portion of the fleet is updated to the new version of your application. -## Overview - -When embracing [Continuous Delivery](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/), a company needs to decide what +When embracing [continuous delivery](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/), an organization needs to decide what type of deployment strategy to use. One of the most popular strategies is canary deployments, where a small portion of the fleet is updated to the new version first. This subset, the canaries, then serve as the proverbial diff --git a/doc/user/project/changelogs.md b/doc/user/project/changelogs.md index a64edd053b1..7e622110291 100644 --- a/doc/user/project/changelogs.md +++ b/doc/user/project/changelogs.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Changelogs +# Changelogs **(FREE)** Changelogs are generated based on commit titles and Git trailers. To be included in a changelog, a commit must contain a specific Git trailer. Changelogs are generated @@ -313,5 +313,5 @@ an error is produced when generating a changelog. ## Related topics -- [Changelog-related endpoints](../../api/repositories.md) in the Repositories API. -- Developer documentation for [changelog entries](../../development/changelog.md) in GitLab. +- [Changelog-related endpoints](../../api/repositories.md) in the Repositories API +- Developer documentation for [changelog entries](../../development/changelog.md) in GitLab diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 52288af101a..6c8edb8c3e5 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -1,10 +1,10 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Connect EKS clusters through cluster certificates (DEPRECATED) **(FREE)** +# Connect EKS clusters through cluster certificates (deprecated) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22392) in GitLab 12.5. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. @@ -25,7 +25,7 @@ use the [GitLab agent](../../clusters/agent/index.md). To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md). -### How to create a new cluster on EKS through cluster certificates (DEPRECATED) +### How to create a new cluster on EKS through cluster certificates (deprecated) > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. @@ -174,11 +174,11 @@ When you create a new cluster, you have the following settings: | Kubernetes cluster name | Your cluster's name. | | Environment scope | The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope). | | Service role | The **EKS IAM role** (**role A**). | -| Kubernetes version | The [Kubernetes version](../../clusters/agent/index.md#supported-cluster-versions) for your cluster. | +| Kubernetes version | The [Kubernetes version](../../clusters/agent/index.md#gitlab-agent-for-kubernetes-supported-cluster-versions) for your cluster. | | Key pair name | The [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) that you can use to connect to your worker nodes. | | VPC | The [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. | | Subnets | The [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) in your VPC where your worker nodes run. Two are required. | -| Security group | The [security group](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) to apply to the EKS-managed Elastic Network Interfaces that are created in your worker node subnets. | +| Security group | The [security group](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-security-groups.html) to apply to the EKS-managed Elastic Network Interfaces that are created in your worker node subnets. | | Instance type | The [instance type](https://aws.amazon.com/ec2/instance-types/) of your worker nodes. | | Node count | The number of worker nodes. | | GitLab-managed cluster | Check if you want GitLab to manage namespaces and service accounts for this cluster. | diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index 0b0555806ce..bb85662d442 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -1,10 +1,10 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Connect existing clusters through cluster certificates (DEPRECATED) **(FREE)** +# Connect existing clusters through cluster certificates (deprecated) **(FREE)** > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index b1c5bbfc4f7..c6561fffa0b 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -1,10 +1,10 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Connect GKE clusters through cluster certificates (DEPRECATED) **(FREE)** +# Connect GKE clusters through cluster certificates (deprecated) **(FREE)** > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. @@ -77,7 +77,7 @@ cluster certificates: - **Zone** - Choose the [region zone](https://cloud.google.com/compute/docs/regions-zones/) under which to create the cluster. - **Number of nodes** - Enter the number of nodes you wish the cluster to have. - - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) + - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-resource) of the Virtual Machine instance to base the cluster on. - **Enable Cloud Run for Anthos** - Check this if you want to use Cloud Run for Anthos for this cluster. See the [Cloud Run for Anthos section](#cloud-run-for-anthos) for more information. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index d3048158958..bba05f1e724 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -1,10 +1,10 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Add a cluster using cluster certificates (DEPRECATED) **(FREE)** +# Add a cluster using cluster certificates (deprecated) **(FREE)** > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index 529e7a6da12..ff30da2ca98 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -1,10 +1,10 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Access controls with cluster certificates (RBAC or ABAC) (DEPRECATED) **(FREE)** +# Access controls with cluster certificates (RBAC or ABAC) (deprecated) **(FREE)** > - Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index 173f1f39a66..31d5a73757a 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -1,10 +1,10 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Deploy to a Kubernetes cluster with cluster certificates (DEPRECATED) **(FREE)** +# Deploy to a Kubernetes cluster with cluster certificates (deprecated) **(FREE)** > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index b2a4bd85de4..b321646d8d8 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -1,10 +1,10 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab-managed clusters (DEPRECATED) **(FREE)** +# GitLab-managed clusters (deprecated) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 11.5. > - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 94513fc7124..5ce1994ba36 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,10 +1,10 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Project-level Kubernetes clusters (certificate-based) (DEPRECATED) **(FREE)** +# Project-level Kubernetes clusters (certificate-based) (deprecated) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index c79f250da7a..c8f49b1917d 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -1,10 +1,10 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Multiple clusters per project with cluster certificates (DEPRECATED) **(FREE)** +# Multiple clusters per project with cluster certificates (deprecated) **(FREE)** > - Introduced in GitLab 10.3 > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) from GitLab Premium to GitLab Free in 13.2. diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index df0ffff8561..a985436d67d 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -107,7 +107,7 @@ the components outlined above and the pre-loaded demo runbook. ''' We set user's id, login and access token on single user image to enable repository integration for JupyterHub. - See: https://gitlab.com/gitlab-org/gitlab-foss/issues/47138#note_154294790 + See: https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47138#note_154294790 ''' auth_state = await spawner.user.get_auth_state() diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 9de9d445965..f9244177aa5 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -1,373 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'codeowners/index.md' +remove_date: '2023-07-07' --- -# Code Owners **(PREMIUM)** +This document was moved to [another location](codeowners/index.md). -> Moved to GitLab Premium in 13.9. - -Code Owners define who develops and maintains a feature, and own the resulting -files or directories in a repository. - -- The users you define as Code Owners are displayed in the UI when you browse directories. -- You can set your merge requests so they must be approved by Code Owners before merge. -- You can protect a branch and allow only Code Owners to approve changes to the branch. - -<div class="video-fallback"> - Video introduction: <a href="https://www.youtube.com/watch?v=RoyBySTUSB0">Code Owners</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube-nocookie.com/embed/RoyBySTUSB0" frameborder="0" allowfullscreen> </iframe> -</figure> - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> - -Use Code Owners and approvers together with -[approval rules](merge_requests/approvals/rules.md) to build a flexible approval -workflow: - -- Use **Code Owners** to define the users who have domain expertise for specific paths in your repository. -- Use **Approvers** and **Approval rules** to define domains of expertise (such as a security team) - that are not scoped to specific file paths in your repository. - - **Approvers** define the users. - - **Approval rules** define when these users can approve work, and whether or not their approval is required. - -For example: - -| Type | Name | Scope | Comment | -|------|------|--------|------------| -| Approval rule | UX | All files | A user experience (UX) team member reviews the user experience of all changes made in your project. | -| Approval rule | Security | All files | A security team member reviews all changes for vulnerabilities. | -| Code Owner approval rule | Frontend: Code Style | `*.css` files | A frontend engineer reviews CSS file changes for adherence to project style standards. | -| Code Owner approval rule | Backend: Code Review | `*.rb` files | A backend engineer reviews the logic and code style of Ruby files. | - -## Code Owners file - -A `CODEOWNERS` file (with no extension) can specify users or [shared groups](members/share_project_with_groups.md) -that are responsible for specific files and directories in a repository. Each repository -can have a single `CODEOWNERS` file, and it must be found one of these three locations: - -- In the root directory of the repository. -- In the `.gitlab/` directory. -- In the `docs/` directory. - -A CODEOWNERS file in any other location is ignored. - -## Set up Code Owners - -1. Create a file named `CODEOWNERS` (with no extension) in one of these locations: - -- In the root directory of the repository -- In the `.gitlab/` directory -- In the `docs/` directory - -1. In the file, enter text that follows one of these patterns: - - ```plaintext - # Code Owners for a file - filename @username1 @username2 - - # Code Owners for a directory - directoryname/ @username1 @username2 - - # All group members as Code Owners for a file - filename @groupname - - # All group members as Code Owners for a directory - directoryname/ @groupname - ``` - -The Code Owners are now displayed in the UI. They apply to the current branch only. - -Next steps: - -- [Add Code Owners as merge request approvers](merge_requests/approvals/rules.md#code-owners-as-eligible-approvers). -- Set up [Code Owner approval on a protected branch](protected_branches.md#require-code-owner-approval-on-a-protected-branch). - -## Groups as Code Owners - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab 12.1. -> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. - -You can use members of groups and subgroups as Code Owners for projects: - -```mermaid -graph TD - A[Parent group X] -->|owns| B[Project A] - A -->|contains| C[Subgroup Y] - C -->|owns| D[Project B] - A-. inherits ownership .-> D -``` - -In this example: - -- **Parent group X** (`group-x`) owns **Project A**. -- **Parent group X** also contains a subgroup, **Subgroup Y**. (`group-x/subgroup-y`) -- **Subgroup Y** owns **Project B**. - -The eligible Code Owners are: - -- **Project A**: the members of **Group X** only, because **Project A** doesn't belong to **Subgroup Y**. -- **Project B**: the members of both **Group X** and **Subgroup Y**. - -You can [invite](members/share_project_with_groups.md) **Subgroup Y** to **Project A** -so that their members also become eligible Code Owners. - -```mermaid -graph LR - A[Parent group X] -->|owns| B[Project A] - A -->|also contains| C[Subgroup Y] - C -.->D{Invite Subgroup Y<br/>to Project A?} -.->|yes| F[Approvals can be<br/> required] -.-> B - D{Invite Subgroup Y<br/>to Project A?} -.->|no| I[Subgroup Y cannot be<br /> an approver] -.-> B - C -.->E{Add Subgroup Y<br/>as Code Owners<br/>to Project A?} -.->|yes| H[Approvals can only<br/>be optional] -.-> B -``` - -If you do not invite **Subgroup Y** to **Project A**, but make them Code Owners, their approval -of the merge request becomes optional. - -Inviting **Subgroup Y** to a parent group of **Project A** -[is not supported](https://gitlab.com/gitlab-org/gitlab/-/issues/288851). To set **Subgroup Y** as -Code Owners, add this group directly to the project itself. - -NOTE: -For approval to be required, groups as Code Owners must have a direct membership -(not inherited membership) in the project. Approval can only be optional for groups -that inherit membership. Members in the Code Owners group also must be direct members, -and not inherit membership from any parent groups. - -### Add a group as a Code Owner - -To set a group as a Code Owner: - -In the `CODEOWNERS` file, enter text that follows one of these patterns: - -```plaintext -# All group members as Code Owners for a file -file.md @group-x - -# All subgroup members as Code Owners for a file -file.md @group-x/subgroup-y - -# All group and subgroup members as Code Owners for a file -file.md @group-x @group-x/subgroup-y -``` - -## When a file matches multiple `CODEOWNERS` entries - -When a file matches multiple entries in the `CODEOWNERS` file, -the users from last pattern matching the file are used. - -For example, in the following `CODEOWNERS` file: - -```plaintext -README.md @user1 - -# This line would also match the file README.md -*.md @user2 -``` - -The Code Owner for `README.md` would be `@user2`. - -If you use sections, the last pattern matching the file for each section is used. -For example, in a `CODEOWNERS` file using sections: - -```plaintext -[README Owners] -README.md @user1 @user2 -internal/README.md @user4 - -[README other owners] -README.md @user3 -``` - -The Code Owners for the `README.md` in the root directory are `@user1`, `@user2`, -and `@user3`. The Code Owners for `internal/README.md` are `@user4` and `@user3`. - -Only one CODEOWNERS pattern can match per file path. - -### Organize Code Owners by putting them into sections - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab 13.2 [with a flag](../../administration/feature_flags.md) named `sectional_codeowners`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. Feature flag `sectional_codeowners` removed. - -You can organize Code Owners by putting them into named sections. - -You can use sections for shared directories, so that multiple -teams can be reviewers. - -To add a section to the `CODEOWNERS` file, enter a section name in brackets, -followed by the files or directories, and users, groups, or subgroups: - -```plaintext -[README Owners] -README.md @user1 @user2 -internal/README.md @user2 -``` - -Each Code Owner in the merge request widget is listed under a label. -The following image shows a **Groups** and **Documentation** section: - - - -### Sections with duplicate names - -If multiple sections have the same name, they are combined. -Also, section headings are not case-sensitive. For example: - -```plaintext -[Documentation] -ee/docs/ @docs -docs/ @docs - -[Database] -README.md @database -model/db/ @database - -[DOCUMENTATION] -README.md @docs -``` - -This code results in three entries under the **Documentation** section header, and two -entries under **Database**. The entries defined under the sections **Documentation** and -**DOCUMENTATION** are combined, using the case of the first section. - -### Make a Code Owners section optional - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab 13.8. - -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. - -In this example, the `[Go]` section is optional: - -```plaintext -[Documentation] -*.md @root - -[Ruby] -*.rb @root - -^[Go] -*.go @root -``` - -The optional Code Owners section displays in merge requests under the **Approval Rules** area: - - - -If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the section is required. - -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. - -### Allowed to Push - -The Code Owner approval and protected branch features do not apply to users who -are **Allowed to push**. - -## Example `CODEOWNERS` file - -```plaintext -# This is an example of a CODEOWNERS file. -# Lines that start with `#` are ignored. - -# app/ @commented-rule - -# Specify a default Code Owner by using a wildcard: -* @default-codeowner - -# Specify multiple Code Owners by using a tab or space: -* @multiple @code @owners - -# Rules defined later in the file take precedence over the rules -# defined before. -# For example, for all files with a filename ending in `.rb`: -*.rb @ruby-owner - -# Files with a `#` can still be accessed by escaping the pound sign: -\#file_with_pound.rb @owner-file-with-pound - -# Specify multiple Code Owners separated by spaces or tabs. -# In the following case the CODEOWNERS file from the root of the repo -# has 3 Code Owners (@multiple @code @owners): -CODEOWNERS @multiple @code @owners - -# You can use both usernames or email addresses to match -# users. Everything else is ignored. For example, this code -# specifies the `@legal` and a user with email `janedoe@gitlab.com` as the -# owner for the LICENSE file: -LICENSE @legal this_does_not_match janedoe@gitlab.com - -# Use group names to match groups, and nested groups to specify -# them as owners for a file: -README @group @group/with-nested/subgroup - -# End a path in a `/` to specify the Code Owners for every file -# nested in that directory, on any level: -/docs/ @all-docs - -# End a path in `/*` to specify Code Owners for every file in -# a directory, but not nested deeper. This code matches -# `docs/index.md` but not `docs/projects/index.md`: -/docs/* @root-docs - -# Include `/**` to specify Code Owners for all subdirectories -# in a directory. This rule matches `docs/projects/index.md` or -# `docs/development/index.md` -/docs/**/*.md @root-docs - -# This code makes matches a `lib` directory nested anywhere in the repository: -lib/ @lib-owner - -# This code match only a `config` directory in the root of the repository: -/config/ @config-owner - -# If the path contains spaces, escape them like this: -path\ with\ spaces/ @space-owner - -# Code Owners section: -[Documentation] -ee/docs @docs -docs @docs - -[Database] -README.md @database -model/db @database - -# This section is combined with the previously defined [Documentation] section: -[DOCUMENTATION] -README.md @docs -``` - -## Troubleshooting - -### Approvals shown as optional - -A Code Owner approval rule is optional if any of these conditions are true: - -- The user or group are not a member of the project. Code Owners [cannot inherit from parent groups](https://gitlab.com/gitlab-org/gitlab/-/issues/288851/). -- [Code Owner approval on a protected branch](protected_branches.md#require-code-owner-approval-on-a-protected-branch) has not been set up. -- The section is [marked as optional](#make-a-code-owners-section-optional). - -### Approvals do not show - -Code Owner approval rules only update when the merge request is created. -If you update the `CODEOWNERS` file, close the merge request and create a new one. - -### User not shown as possible approver - -A user might not show as an approver on the Code Owner merge request approval rules -if any of these conditions are true: - -- A rule prevents the specific user from approving the merge request. - Check the project [merge request approval](merge_requests/approvals/settings.md#edit-merge-request-approval-settings) settings. -- A Code Owner group has a visibility of **private**, and the current user is not a - member of the Code Owner group. +<!-- This redirect file can be deleted after <2023-07-07>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/codeowners/index.md b/doc/user/project/codeowners/index.md new file mode 100644 index 00000000000..e69dba6f977 --- /dev/null +++ b/doc/user/project/codeowners/index.md @@ -0,0 +1,381 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Code Owners **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. + +Use the Code Owners feature to define who has expertise for specific parts of your project's codebase. +Define the owners of files and directories in a repository to: + +- **Require owners to approve changes.** Combine protected branches with Code Owners to require + experts to approve merge requests before they merge into a protected branch. +- **Identify owners.** Code Owner names are displayed on the files and directories they own: +  + +Use Code Owners in combination with merge request +[approval rules](../merge_requests/approvals/rules.md) (either optional or required) +to build a flexible approval workflow: + +- Use **Code Owners** to ensure quality. Define the users who have domain expertise + for specific paths in your repository. +- Use **Approval rules** to define areas of expertise that don't correspond to specific + file paths in your repository. Approval rules help guide merge request creators to + the correct set of reviewers, such as frontend developers or a security team. + +For example: + +| Type | Name | Scope | Comment | +|------|------|--------|------------| +| Approval rule | UX | All files | A user experience (UX) team member reviews the user experience of all changes made in your project. +| Approval rule | Security | All files | A security team member reviews all changes for vulnerabilities. +| Code Owner approval rule | Frontend: Code Style | `*.css` files | A frontend engineer reviews CSS file changes for adherence to project style standards. +| Code Owner approval rule | Backend: Code Review | `*.rb` files | A backend engineer reviews the logic and code style of Ruby files. + +<div class="video-fallback"> + Video introduction: <a href="https://www.youtube.com/watch?v=RoyBySTUSB0">Code Owners</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/RoyBySTUSB0" frameborder="0" allowfullscreen> </iframe> +</figure> + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> + +## View Code Owners of a file or directory + +To view the Code Owners of a file or directory: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Files**. +1. Go to the file or directory you want to see the Code Owners for. +1. Optional. Select a branch or tag. + +GitLab shows the Code Owners at the top of the page. + +## Set up Code Owners + +1. Create a `CODEOWNERS` file in your [preferred location](#code-owners-file). +1. Define some rules in the file following the [Code Owners syntax reference](reference.md). + Some suggestions: + - Configure [All eligible approvers](../merge_requests/approvals/rules.md#code-owners-as-eligible-approvers) approval rule. + - [Require Code Owner approval](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) on a protected branch. +1. Commit your changes, and push them up to GitLab. + +### Code Owners file + +A `CODEOWNERS` file (with no extension) specifies the users or +[shared groups](../members/share_project_with_groups.md) responsible for +specific files and directories in a repository. + +Each repository uses a single `CODEOWNERS` file. GitLab checks these locations +in your repository in this order. The first `CODEOWNERS` file found is used, and +all others are ignored: + +1. In the root directory: `./CODEOWNERS`. +1. In the `docs` directory: `./docs/CODEOWNERS`. +1. In the `.gitlab` directory: `./.gitlab/CODEOWNERS`. + +### Add a group as a Code Owner + +> Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. + +To set the members of a group or subgroup as a Code Owner: + +In the `CODEOWNERS` file, enter text that follows one of these patterns: + +```plaintext +# All group members as Code Owners for a file +file.md @group-x + +# All subgroup members as Code Owners for a file +file.md @group-x/subgroup-y + +# All group and subgroup members as Code Owners for a file +file.md @group-x @group-x/subgroup-y +``` + +#### Group inheritance and eligibility + +> Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. + +```mermaid +graph TD + A[Parent group X] -->|owns| B[Project A] + A -->|contains| C[Subgroup Y] + C -->|owns| D[Project B] + A-. inherits ownership .-> D +``` + +In this example: + +- **Parent group X** (`group-x`) owns **Project A**. +- **Parent group X** also contains a subgroup, **Subgroup Y**. (`group-x/subgroup-y`) +- **Subgroup Y** owns **Project B**. + +The eligible Code Owners are: + +- **Project A**: the members of **Group X** only, because **Project A** doesn't belong to **Subgroup Y**. +- **Project B**: the members of both **Group X** and **Subgroup Y**. + +##### Inviting subgroups to projects in parent groups + +You can [invite](../members/share_project_with_groups.md) **Subgroup Y** to **Project A** +so that their members also become eligible Code Owners. + +```mermaid +graph LR + A[Parent group X] -->|owns| B[Project A] + A -->|also contains| C[Subgroup Y] + C -.->D{Invite Subgroup Y<br/>to Project A?} -.->|yes| E[Members of Subgroup Y<br/>can submit Approvals] + D{Invite Subgroup Y<br/>to Project A?} -.->|no| F[Members of Subgroup Y<br />cannot submit Approvals] + E -.->|Add Subgroup Y<br/> as Code Owner to Project A| I[Approvals can be<br/>required] -.-> B + F -.-> |Add Subgroup Y<br/> as Code Owners to Project A| J[Approvals can only<br/>be optional] -.-> B +``` + +If you do not invite **Subgroup Y** to **Project A**, but make them Code Owners, their approval +of the merge request becomes optional. + +##### Inviting subgroups to parent groups + +Inviting **Subgroup Y** to a parent group of **Project A** +[is not supported](https://gitlab.com/gitlab-org/gitlab/-/issues/288851). To set **Subgroup Y** as +Code Owners [invite this group directly to the project](#inviting-subgroups-to-projects-in-parent-groups) itself. + +NOTE: +For approval to be required, groups as Code Owners must have a direct membership +(not inherited membership) in the project. Approval can only be optional for groups +that inherit membership. Members in the Code Owners group also must be direct members, +and not inherit membership from any parent groups. + +### Define more specific owners for more specifically defined files or directories + +When a file or directory matches multiple entries in the `CODEOWNERS` file, +the users from last pattern matching the file or directory are used. This enables you +to define more specific owners for more specifically defined files or directories, when +you order the entries in a sensible way. + +For example, in the following `CODEOWNERS` file: + +```plaintext +# This line would match the file terms.md +*.md @doc-team + +# This line would also match the file terms.md +terms.md @legal-team +``` + +The Code Owner for `terms.md` would be `@legal-team`. + +If you use sections, the last pattern matching the file or directory for each section is used. +For example, in a `CODEOWNERS` file using sections: + +```plaintext +[README Owners] +README.md @user1 @user2 +internal/README.md @user4 + +[README other owners] +README.md @user3 +``` + +The Code Owners for the `README.md` in the root directory are `@user1`, `@user2`, +and `@user3`. The Code Owners for `internal/README.md` are `@user4` and `@user3`. + +Only one CODEOWNERS pattern per section is matched to a file path. + +### Organize Code Owners by putting them into sections + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab 13.2 [with a flag](../../../administration/feature_flags.md) named `sectional_codeowners`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. Feature flag `sectional_codeowners` removed. + +You can organize Code Owners by putting them into named sections. + +You can use sections for shared directories, so that multiple +teams can be reviewers. + +To add a section to the `CODEOWNERS` file, enter a section name in brackets, +followed by the files or directories, and users, groups, or subgroups: + +```plaintext +[README Owners] +README.md @user1 @user2 +internal/README.md @user2 +``` + +Each Code Owner in the merge request widget is listed under a label. +The following image shows a **Groups** and **Documentation** section: + + + +#### Set default owner for a section + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371711) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `codeowners_default_owners`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115888) in GitLab 15.11. Feature flag `codeowners_default_owners` removed. + +If multiple file paths inside a section share the same ownership, define a default +Code Owner for the section. All paths in that section inherit this default, unless +you override the section default on a specific line. + +Default owners are applied when specific owners are not specified for file paths. +Specific owners defined beside the file path override default owners: + +```plaintext +[Documentation] @docs-team +docs/ +README.md + +[Database] @database-team +model/db/ +config/db/database-setup.md @docs-team +``` + +In this example: + +- `@docs-team` owns all items in the `Documentation` section. +- `@database-team` owns all items in the `Database` section except + `config/db/database-setup.md`, which has an override assigning it to `@docs-team`. + +To combine the syntax for default owners with [optional sections](#make-a-code-owners-section-optional) +and required approvals, place default owners at the end: + +```plaintext +[Documentation][2] @docs-team +docs/ +README.md + +^[Database] @database-team +model/db/ +config/db/database-setup.md @docs-team +``` + +#### Sections with duplicate names + +If multiple sections have the same name, they are combined. +Also, section headings are not case-sensitive. For example: + +```plaintext +[Documentation] +ee/docs/ @docs +docs/ @docs + +[Database] +README.md @database +model/db/ @database + +[DOCUMENTATION] +README.md @docs +``` + +This code results in three entries under the **Documentation** section header, and two +entries under **Database**. The entries defined under the sections **Documentation** and +**DOCUMENTATION** are combined, using the case of the first section. + +#### Make a Code Owners section optional + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab 13.8. + +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. + +In this example, the `[Go]` section is optional: + +```plaintext +[Documentation] +*.md @root + +[Ruby] +*.rb @root + +^[Go] +*.go @root +``` + +The optional Code Owners section displays in merge requests under the **Approval Rules** area: + + + +If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the section is required. + +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. + +### Require multiple approvals from Code Owners + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335451) in GitLab 15.9. + +You can require multiple approvals for the Code Owners sections under the Approval Rules area in merge requests. +Append the section name with a number `n` in brackets. This requires `n` approvals from the Code Owners in this section. +Please note valid entries for `n` are integers `≥ 1`. `[1]` is optional as it is the default. Invalid values for `n` are treated as `1`. + +WARNING: +[Issue #384881](https://gitlab.com/gitlab-org/gitlab/-/issues/385881) proposes changes +to the behavior of this setting. Do not intentionally set invalid values. They may +become valid in the future, and cause unexpected behavior. + +Please confirm you enabled `Require approval from code owners` in `Settings > Repository > Protected branches`, otherwise the Code Owner approvals will be optional. + +In this example, the `[Documentation]` section requires 2 approvals: + +```plaintext +[Documentation][2] +*.md @tech-writer-team + +[Ruby] +*.rb @dev-team +``` + +The `Documentation` Code Owners section under the **Approval Rules** area displays 2 approvals are required: + + + +### Allowed to Push + +The Code Owner approval and protected branch features do not apply to users who +are **Allowed to push**. + +## Technical Resources + +[Code Owners development guidelines](../../../development/code_owners/index.md) + +## Troubleshooting + +For more information about how the Code Owners feature handles errors, see the +[Code Owners reference](reference.md). + +### Approvals shown as optional + +A Code Owner approval rule is optional if any of these conditions are true: + +- The user or group are not a member of the project. Code Owners [cannot inherit from parent groups](https://gitlab.com/gitlab-org/gitlab/-/issues/288851/). +- [Code Owner approval on a protected branch](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) has not been set up. +- The section is [marked as optional](#make-a-code-owners-section-optional). + +### Approvals do not show + +Code Owner approval rules only update when the merge request is created. +If you update the `CODEOWNERS` file, close the merge request and create a new one. + +### User not shown as possible approver + +A user might not show as an approver on the Code Owner merge request approval rules +if any of these conditions are true: + +- A rule prevents the specific user from approving the merge request. + Check the project [merge request approval](../merge_requests/approvals/settings.md#edit-merge-request-approval-settings) settings. +- A Code Owner group has a visibility of **private**, and the current user is not a + member of the Code Owner group. +- Current user is an external user who does not have permission to the internal Code Owner group. + +### Approval rule is invalid. GitLab has approved this rule automatically to unblock the merge request + +This message may appear if an approval rule uses a Code Owner that is not a direct member of the project. +Check that the group or user has been invited to the project. diff --git a/doc/user/project/codeowners/reference.md b/doc/user/project/codeowners/reference.md new file mode 100644 index 00000000000..d486b689638 --- /dev/null +++ b/doc/user/project/codeowners/reference.md @@ -0,0 +1,371 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Code Owners syntax and error handling **(PREMIUM)** + +This page describes the syntax and error handling used in Code Owners files, +and provides an example file. + +## Code Owners syntax + +### Comments + +Lines beginning with `#` are ignored: + +```plaintext +# This is a comment +``` + +### Sections + +Sections are groups of entries. A section begins with a section heading in square brackets, followed by the entries. + +```plaintext +[Section name] +/path/of/protected/file.rb @username +/path/of/protected/dir/ @group +``` + +#### Section headings + +Section headings must always have a name. They can also be made optional, or +require a number of approvals. A list of default owners can be added to the section heading line. + +```plaintext +# Required section +[Section name] + +# Optional section +^[Section name] + +# Section requiring 5 approvals +[Section name][5] + +# Section with @username as default owner +[Section name] @username + +# Section with @group and @subgroup as default owners and requiring 2 approvals +[Section name][2] @group @subgroup +``` + +#### Section names + +Sections names are defined between square brackets. Section names are not case-sensitive. +[Sections with duplicate names](index.md#sections-with-duplicate-names) are combined. + +```plaintext +[Section name] +``` + +#### Required sections + +Required sections do not include `^` before the [section name](#section-names). + +```plaintext +[Required section] +``` + +#### Optional sections + +Optional sections include a `^` before the [section name](#section-names). + +```plaintext +^[Optional section] +``` + +#### Sections requiring multiple approvals + +Sections requiring multiple approvals include the number of approvals in square brackets after the [section name](#section-names). + +```plaintext +[Section requiring 5 approvals][5] +``` + +NOTE: +Optional sections ignore the number of approvals required. + +#### Sections with default owners + +You can define a default owner for the entries in a section by appending the owners to the [section heading](#section-headings). + +```plaintext +# Section with @username as default owner +[Section name] @username + +# Section with @group and @subgroup as default owners and requiring 2 approvals +[Section name][2] @group @subgroup +``` + +### Code Owner entries + +Each Code Owner entry includes a path followed by one or more owners. + +```plaintext +README.md @username1 +``` + +NOTE: +If an entry is duplicated in a section, [the last entry is used from each section.](index.md#define-more-specific-owners-for-more-specifically-defined-files-or-directories) + +### Relative paths + +If a path does not start with a `/`, the path is treated as if it starts with +a [globstar](#globstar-paths). `README.md` is treated the same way as `/**/README.md`: + +```plaintext +# This will match /README.md, /internal/README.md, /app/lib/README.md +README.md @username + +# This will match /internal/README.md, /docs/internal/README.md, /docs/api/internal/README.md +internal/README.md +``` + +### Absolute paths + +If a path starts with a `/` it matches the root of the repository. + +```plaintext +# Matches only the file named `README.md` in the root of the repository. +/README.md + +# Matches only the file named `README.md` inside the `/docs` directory. +/docs/README.md +``` + +### Directory paths + +If a path ends with `/`, the path matches any file in the directory. + +```plaintext +# This is the same as `/docs/**/*` +/docs/ +``` + +### Wildcard paths + +Wildcards can be used to match one of more characters of a path. + +```plaintext +# Any markdown files in the docs directory +/docs/*.md @username + +# /docs/index file of any filetype +# For example: /docs/index.md, /docs/index.html, /docs/index.xml +/docs/index.* @username + +# Any file in the docs directory with 'spec' in the name. +# For example: /docs/qa_specs.rb, /docs/spec_helpers.rb, /docs/runtime.spec +/docs/*spec* @username + +# README.md files one level deep within the docs directory +# For example: /docs/api/README.md +/docs/*/README.md @username +``` + +### Globstar paths + +Globstars (`**`) can be used to match zero or more directories and subdirectories. + +```plaintext +# This will match /docs/index.md, /docs/api/index.md, /docs/api/graphql/index.md +/docs/**/index.md +``` + +### Entry owners + +Entries must be followed by one or more owner. These can be groups, subgroups, +and users. Order of owners is not important. + +```plaintext +/path/to/entry.rb @group +/path/to/entry.rb @group/subgroup +/path/to/entry.rb @user +/path/to/entry.rb @group @group/subgroup @user +``` + +#### Groups as entry owners + +Groups and subgroups can be owners of an entry. +Each entry can be owned by [one or more owners](#entry-owners). +For more details see the [Add a group as a Code Owner](index.md#add-a-group-as-a-code-owner). + +```plaintext +/path/to/entry.rb @group +/path/to/entry.rb @group/subgroup +/path/to/entry.rb @group @group/subgroup +``` + +### Users as entry owners + +Users can be owners of an entry. Each entry can be owned by +[one or more owners](#entry-owners). + +```plaintext +/path/to/entry.rb @username1 +/path/to/entry.rb @username1 @username2 +``` + +## Error handling in Code Owners + +### Entries with spaces + +Paths containing whitespace must be escaped with backslashes: `path\ with\ spaces/*.md`. +Without the backslashes, the path after the first whitespace is parsed as an owner. +GitLab the parses `folder with spaces/*.md @group` into +`path: "folder", owners: " with spaces/*.md @group"`. + +### Unparsable sections + +If a section heading cannot be parsed, the section is: + +1. Parsed as an entry. +1. Added to the previous section. +1. If no previous section exists, the section is added to the default section. + +For example, this file is missing a square closing bracket: + +```plaintext +* @group + +[Section name +docs/ @docs_group +``` + +GitLab recognizes the heading `[Section name` as an entry. The default section includes 3 rules: + +- Default section + - `*` owned by `@group` + - `[Section` owned by `name` + - `docs/` owned by `@docs_group` + +This file contains an unescaped space between the words `Section` and `name`. +GitLab recognizes the intended heading as an entry: + +```plaintext +[Docs] +docs/**/* @group + +[Section name]{2} @group +docs/ @docs_group +``` + +The `[Docs]` section then includes 3 rules: + +- `docs/**/*` owned by `@group` +- `[Section` owned by `name]{2} @group` +- `docs/` owned by `@docs_group` + +### Malformed owners + +Each entry must contain 1 or more owners to be valid, malformed owners are ignored. +For example `/path/* @group user_without_at_symbol @user_with_at_symbol` +is owned by `@group` and `@user_with_at_symbol`. + +### Inaccessible or incorrect owners + +Inaccessible or incorrect owners are ignored. For example, if `@group`, `@username`, +and `example@gitlab.com` are accessible on the project and we create an entry: + +```plaintext +* @group @grou @username @i_left @i_dont_exist example@gitlab.com invalid@gitlab.com +``` + +GitLab ignores `@grou`, `@i_left`, `@i_dont_exist`, and `invalid@gitlab.com`. + +For more information on who is accessible, see [Add a group as a Code Owner](index.md#add-a-group-as-a-code-owner). + +### Zero owners + +If an entry includes no owners, or zero [accessible owners](#inaccessible-or-incorrect-owners) +exist, the entry is invalid. Because this rule can never be satisfied, GitLab +auto-approves it in merge requests. + +NOTE: +When a protected branch has `Require code owner approval` enabled, rules with +zero owners are still honored. + +### Less than 1 required approval + +When [defining the number of approvals](index.md#require-multiple-approvals-from-code-owners) for a section, +the minimum number of approvals is `1`. Setting the number of approvals to +`0` results in GitLab requiring one approval. + +## Example `CODEOWNERS` file + +```plaintext +# This is an example of a CODEOWNERS file. +# Lines that start with `#` are ignored. + +# app/ @commented-rule + +# Specify a default Code Owner by using a wildcard: +* @default-codeowner + +# Specify multiple Code Owners by using a tab or space: +* @multiple @code @owners + +# Rules defined later in the file take precedence over the rules +# defined before. +# For example, for all files with a filename ending in `.rb`: +*.rb @ruby-owner + +# Files with a `#` can still be accessed by escaping the pound sign: +\#file_with_pound.rb @owner-file-with-pound + +# Specify multiple Code Owners separated by spaces or tabs. +# In the following case the CODEOWNERS file from the root of the repo +# has 3 Code Owners (@multiple @code @owners): +CODEOWNERS @multiple @code @owners + +# You can use both usernames or email addresses to match +# users. Everything else is ignored. For example, this code +# specifies the `@legal` and a user with email `janedoe@gitlab.com` as the +# owner for the LICENSE file: +LICENSE @legal this_does_not_match janedoe@gitlab.com + +# Use group names to match groups, and nested groups to specify +# them as owners for a file: +README @group @group/with-nested/subgroup + +# End a path in a `/` to specify the Code Owners for every file +# nested in that directory, on any level: +/docs/ @all-docs + +# End a path in `/*` to specify Code Owners for every file in +# a directory, but not nested deeper. This code matches +# `docs/index.md` but not `docs/projects/index.md`: +/docs/* @root-docs + +# Include `/**` to specify Code Owners for all subdirectories +# in a directory. This rule matches `docs/projects/index.md` or +# `docs/development/index.md` +/docs/**/*.md @root-docs + +# This code makes matches a `lib` directory nested anywhere in the repository: +lib/ @lib-owner + +# This code match only a `config` directory in the root of the repository: +/config/ @config-owner + +# If the path contains spaces, escape them like this: +path\ with\ spaces/ @space-owner + +# Code Owners section: +[Documentation] +ee/docs @docs +docs @docs + +# Use of default owners for a section. In this case, all files (*) are owned by +the dev team except the README.md and data-models which are owned by other teams. +[Development] @dev-team +* +README.md @docs-team +data-models/ @data-science-team + +# This section is combined with the previously defined [Documentation] section: +[DOCUMENTATION] +README.md @docs +``` diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index a68f9550ebf..09a443614d0 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -1,11 +1,11 @@ --- -stage: Release -group: Release +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto, reference --- -# Deploy boards (DEPRECATED) **(FREE)** +# Deploy boards (deprecated) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in GitLab 9.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) from GitLab Premium to GitLab Free in 13.8. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index fc88535dc77..13ee07097e1 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -15,8 +15,7 @@ Depending on your needs, you might want to use a [deploy token](../deploy_tokens |------------------|-------------|--------------| | Sharing | Shareable between multiple projects, even those in different groups. | Belong to a project or group. | | Source | Public SSH key generated on an external host. | Generated on your GitLab instance, and is provided to users only at creation time. | -| Validity | Valid as long as it's registered and enabled, and the user that created it exists. | Can be given an expiration date. | -| Registry access | Cannot access a package registry. | Can read from and write to a package registry. | +| Accessible resources | Git repository over SSH | Git repository over HTTP, package registry, and container registry. | Deploy keys can't be used for Git operations if [external authorization](../../admin_area/settings/external_authorization.md) is enabled. @@ -41,10 +40,8 @@ A deploy key is given a permission level when it is created: You can change a deploy key's permission level after creating it. Changing a project deploy key's permissions only applies for the current project. -When a read-write deploy key is used to push a commit, GitLab checks if the creator of the -deploy key has permission to access the resource. - -For example: +Although a deploy key is a secret that isn't associated with a specific user, +GitLab authorizes the creator of the deploy key if the Git-command triggers additional processes. For example: - When a deploy key is used to push a commit to a [protected branch](../protected_branches.md), the _creator_ of the deploy key must have access to the branch. @@ -52,6 +49,15 @@ For example: deploy key must have access to the CI/CD resources, including protected environments and secret variables. +## Security implications + +The intended use case for deploy keys is for non-human interaction with GitLab, for example: an automated script running on a server in your organization. +As with all sensitive information, you should ensure only those who need access to the secret can read it. +For human interactions, use credentials tied to users such as Personal Access Tokens. + +To help detect a potential secret leak, you can use the +[Audit Event](../../../administration/audit_event_streaming.md#example-payloads-for-ssh-events-with-deploy-key) feature. + ## View deploy keys To view the deploy keys available to a project: @@ -80,6 +86,7 @@ Prerequisites: 1. Complete the fields. 1. Optional. To grant `read-write` permission, select the **Grant write permissions to this key** checkbox. +1. Optional. Update the **Expiration date**. A project deploy key is enabled when it is created. You can modify only a project deploy key's name and permissions. @@ -88,9 +95,9 @@ name and permissions. Prerequisites: -- You must have administrator access. -- [Generate an SSH key pair](../../ssh.md#generate-an-ssh-key-pair). Put the private SSH - key on the host that requires access to the repository. +- You must have administrator access to the instance. +- You must [generate an SSH key pair](../../ssh.md#generate-an-ssh-key-pair). +- You must put the private SSH key on the host that requires access to the repository. To create a public deploy key: @@ -153,7 +160,7 @@ There are a few scenarios where a deploy key fails to push to a - The owner associated to a deploy key does not have access to the protected branch. - The owner associated to a deploy key does not have [membership](../members/index.md) to the project of the protected branch. -- **No one** is selected in [the **Allowed to push** section](../protected_branches.md#configure-a-protected-branch) of the protected branch. +- **No one** is selected in [the **Allowed to push and merge** section](../protected_branches.md#configure-a-protected-branch) of the protected branch. All deploy keys are associated to an account. Since the permissions for an account can change, this might lead to scenarios where a deploy key that was working is suddenly unable to push to a protected branch. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index cfb382d73e2..a81ccd043bd 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index ffbe7447aa8..f0ced95c8eb 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -16,7 +16,7 @@ You might want to use these templates: - For different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. - For every issue or merge request for a specific project, so the layout is consistent. -- For a [Service Desk email template](service_desk.md#new-service-desk-issues). +- For a [Service Desk email template](service_desk.md#use-a-custom-template-for-service-desk-issues). For description templates to work, they must be: @@ -46,10 +46,11 @@ and see if you can find your description template in the **Choose a template** d ## Create a merge request template Similarly to issue templates, create a new Markdown (`.md`) file inside the -`.gitlab/merge_request_templates/` directory in your repository. Commit and -push to your default branch. +`.gitlab/merge_request_templates/` directory in your repository. Unlike issue +templates, merge requests have [additional inheritance rules](merge_requests/creating_merge_requests.md) +that depend on the contents of commit messages and branch names. -To create a merge request description template: +To create a merge request description template for a project: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository**. @@ -87,6 +88,10 @@ For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_templat > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89810) in GitLab 15.7. +NOTE: +This feature is available only for +[the default template](#set-a-default-template-for-merge-requests-and-issues). + When you save a merge request for the first time, GitLab replaces these variables in your merge request template with their values: @@ -95,7 +100,7 @@ your merge request template with their values: | `%{all_commits}` | Messages from all commits in the merge request. Limited to 100 most recent commits. Skips commit bodies exceeding 100 KiB and merge commit messages. | `* Feature introduced` <br><br> `This commit implements feature` <br> `Changelog:added` <br><br> `* Bug fixed` <br><br> `* Documentation improved` <br><br>`This commit introduced better docs.` | | `%{co_authored_by}` | Names and emails of commit authors in a `Co-authored-by` Git commit trailer format. Limited to authors of 100 most recent commits in merge request. | `Co-authored-by: Zane Doe <zdoe@example.com>` <br> `Co-authored-by: Blake Smith <bsmith@example.com>` | | `%{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.` | +| `%{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.` | | `%{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` | @@ -148,11 +153,11 @@ To set a default description template for merge requests, either: - [In GitLab 14.8 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78302), [create a merge request template](#create-a-merge-request-template) named `Default.md` (case insensitive) and save it in `.gitlab/merge_request_templates/`. This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. -- Users on GitLab Premium and higher: set the default template in project settings: +- Users on GitLab Premium and Ultimate: set the default template in project settings: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Merge requests**. - 1. In the **Merge commit message template** section, fill in **Default description template for merge requests**. + 1. In the **Default description template for merge requests** section, fill in the text area. 1. Select **Save changes**. To set a default description template for issues, either: @@ -160,12 +165,12 @@ To set a default description template for issues, either: - [In GitLab 14.8 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78302), [create an issue template](#create-an-issue-template) named `Default.md` (case insensitive) and save it in `.gitlab/issue_templates/`. This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. -- Users on GitLab Premium and higher: set the default template in project settings: +- Users on GitLab Premium and Ultimate: set the default template in project settings: 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Settings**. - 1. Expand **Default issue template**. - 1. Fill in the **Default description template for issues** text area. + 1. On the left sidebar, select **Settings > General**. + 1. Expand **Default description template for issues**. + 1. Fill in the text area. 1. Select **Save changes**. Because GitLab merge request and issues support [Markdown](../markdown.md), you can use it to format @@ -176,7 +181,7 @@ You can also provide `issues_template` and `merge_requests_template` attributes #### Priority of default description templates -When you set [merge request and issue description templates](#set-a-default-template-for-merge-requests-and-issues) +When you set [issue description templates](#set-a-default-template-for-merge-requests-and-issues) in various places, they have the following priorities in a project. The ones higher up override the ones below: @@ -184,6 +189,9 @@ The ones higher up override the ones below: 1. `Default.md` (case insensitive) from the parent group. 1. `Default.md` (case insensitive) from the project repository. +Merge requests have [additional inheritance rules](merge_requests/creating_merge_requests.md) +that depend on the contents of commit messages and branch names. + ## Example description template We use description templates for issues and merge requests in the diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 8d3446994e8..c81ba4b7dd3 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -58,7 +58,7 @@ git-lfs --version ``` If it doesn't recognize this command, you must install it. There are -several [installation methods](https://git-lfs.github.com/) that you can +several [installation methods](https://git-lfs.com/) that you can choose according to your OS. To install it with Homebrew: ```shell @@ -195,8 +195,7 @@ Suggested workflow for shared projects: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in GitLab 8.9. This process allows you to lock one file at a time through the GitLab UI and -requires access to [GitLab Premium](https://about.gitlab.com/pricing/) -or higher tiers. +requires access to the [GitLab Premium or Ultimate tier](https://about.gitlab.com/pricing/). Default branch file and directory locks only apply to the [default branch](repository/branches/default.md) set in the project's settings. @@ -209,7 +208,7 @@ requests that modify locked files. Unlock the file to allow changes. To lock a file: 1. Open the file or directory in GitLab. -1. In the upper right, above the file, select **Lock**. +1. In the upper-right corner, above the file, select **Lock**. 1. On the confirmation dialog box, select **OK**. If you do not have permission to lock the file, the button is not enabled. @@ -221,7 +220,7 @@ To view the user who locked the file (if it was not you), hover over the button. To view and remove file locks: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Locked Files**. +1. On the left sidebar, select **Repository > Locked files**. This list shows all the files locked either through LFS or GitLab UI. diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 1feb17b19c8..698b888a32a 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Git Attributes **(FREE)** +# Git attributes **(FREE)** GitLab supports defining custom [Git attributes](https://git-scm.com/docs/gitattributes) such as what files to treat as binary, and what language to use for syntax highlighting @@ -14,14 +14,41 @@ diffs. To define these attributes, create a file called `.gitattributes` in the root directory of your repository and push it to the default branch of your project. -## Encoding Requirements +## Encoding requirements The `.gitattributes` file _must_ be encoded in UTF-8 and _must not_ contain a Byte Order Mark. If a different encoding is used, the file's contents are ignored. -## Syntax Highlighting +## Support for mixed file encodings + +GitLab attempts to detect the encoding of files automatically, but defaults to UTF-8 unless +the detector is confident of a different type (such as `ISO-8859-1`). Incorrect encoding +detection can result in some characters not displaying in the text, such as accented characters in a +non-UTF-8 encoding. + +Git has built-in support for handling this eventuality and automatically converts files between +a designated encoding and UTF-8 for the repository itself. Configure support for mixed file encoding in the `.gitattributes` +file using the `working-tree-encoding` attribute. + +Example: + +```plaintext +*.xhtml text working-tree-encoding=ISO-8859-1 +``` + +With this example configuration, Git maintains all `.xhtml` files in the repository in ISO-8859-1 +encoding in the local tree, but converts to and from UTF-8 when committing into the repository. GitLab +renders the files accurately as it only sees correctly encoded UTF-8. + +If applying this configuration to an existing repository, files may need to be touched and recommitted +if the local copy has the correct encoding but the repository does not. This can +be performed for the whole repository by running `git add --renormalize .`. + +For more information, see [working-tree-encoding](https://git-scm.com/docs/gitattributes#_working_tree_encoding). + +## Syntax highlighting The `.gitattributes` file can be used to define which language to use when -syntax highlighting files and diffs. See -["Syntax Highlighting"](highlighting.md) for more information. +syntax highlighting files and diffs. For more information, see +[Syntax highlighting](highlighting.md). diff --git a/doc/user/project/img/codeowners_in_UI_v15_10.png b/doc/user/project/img/codeowners_in_UI_v15_10.png Binary files differnew file mode 100644 index 00000000000..c643d333791 --- /dev/null +++ b/doc/user/project/img/codeowners_in_UI_v15_10.png diff --git a/doc/user/project/img/issue_board_system_notes_v13_6.png b/doc/user/project/img/issue_board_system_notes_v13_6.png Binary files differdeleted file mode 100644 index 4958f63541e..00000000000 --- a/doc/user/project/img/issue_board_system_notes_v13_6.png +++ /dev/null diff --git a/doc/user/project/img/multi_approvals_code_owners_sections_v15_9.png b/doc/user/project/img/multi_approvals_code_owners_sections_v15_9.png Binary files differnew file mode 100644 index 00000000000..a7fea76d5b1 --- /dev/null +++ b/doc/user/project/img/multi_approvals_code_owners_sections_v15_9.png diff --git a/doc/user/project/img/protected_tags_list_v12_3.png b/doc/user/project/img/protected_tags_list_v12_3.png Binary files differdeleted file mode 100644 index 6a30f615f2f..00000000000 --- a/doc/user/project/img/protected_tags_list_v12_3.png +++ /dev/null diff --git a/doc/user/project/img/protected_tags_page_v12_3.png b/doc/user/project/img/protected_tags_page_v12_3.png Binary files differdeleted file mode 100644 index 841e19af8a7..00000000000 --- a/doc/user/project/img/protected_tags_page_v12_3.png +++ /dev/null diff --git a/doc/user/project/img/protected_tags_permissions_dropdown_v12_3.png b/doc/user/project/img/protected_tags_permissions_dropdown_v12_3.png Binary files differdeleted file mode 100644 index 913d4725d53..00000000000 --- a/doc/user/project/img/protected_tags_permissions_dropdown_v12_3.png +++ /dev/null diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 7114974d8db..b523e007f0e 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -1,7 +1,6 @@ --- -type: reference, howto stage: Manage -group: Import +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -33,10 +32,13 @@ When importing: ## Prerequisites +> Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. + - [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be enabled. If that integration is not enabled, ask your GitLab administrator to enable it. The Bitbucket Cloud integration is enabled by default on GitLab.com. -- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was - [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. +- [Bitbucket Cloud import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your + GitLab administrator to enable it. The Bitbucket Cloud import source is enabled by default on GitLab.com. +- At least the Maintainer role on the destination group to import to. ## How it works diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index e6d2e3e00b6..4d3a6eb87e0 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -1,7 +1,6 @@ --- -type: reference, howto stage: Manage -group: Import +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -26,11 +25,18 @@ created as private in GitLab as well. > Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. -Prerequisites: +You can import Bitbucket repositories to GitLab. -- An administrator must enable **Bitbucket Server** in **Admin > Settings > General > Visibility and access controls > Import sources**. -- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was - [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. +### Prerequisites + +> Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. + +- [Bitbucket Server import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) + must be enabled. If not enabled, ask your GitLab administrator to enable it. The Bitbucket Server import source is enabled + by default on GitLab.com. +- At least the Maintainer role on the destination group to import to. + +### Import repositories To import your Bitbucket repositories: @@ -120,7 +126,16 @@ If the project import completes but LFS objects can't be downloaded or cloned, y password or personal access token containing special characters. For more information, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337769). +### Pull requests are missing + +Importing large projects spawns a process that can consume a lot of memory. Sometimes you can see messages such as `Sidekiq worker RSS out of range` in the +[Sidekiq logs](../../../administration/logs/index.md#sidekiq-logs). This can mean that MemoryKiller is interrupting the `RepositoryImportWorker` because it's using +too much memory. + +To resolve this problem, temporarily increase the `SIDEKIQ_MEMORY_KILLER_MAX_RSS` environment variable using +[custom environment variables](https://docs.gitlab.com/omnibus/settings/environment-variables.html) from the default `2000000` value to a larger value like `3000000`. +Consider memory constraints on the system before deciding to increase `SIDEKIQ_MEMORY_KILLER_MAX_RSS`. + ## Related topics -For information on automating user, group, and project import API calls, see -[Automate group and project import](index.md#automate-group-and-project-import). +- [Automate group and project import](index.md#automate-group-and-project-import) diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index 0878476d59f..35ed7a043d0 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -1,7 +1,6 @@ --- -type: reference, howto stage: Manage -group: Import +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 00aebb75a50..fb3416a3492 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -1,14 +1,13 @@ --- -type: reference, howto stage: Manage -group: Import +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from CVS **(FREE)** [CVS](https://savannah.nongnu.org/projects/cvs) is an old centralized version -control system similar to [SVN](svn.md). +control system similar to [SVN](https://subversion.apache.org/). ## CVS vs Git @@ -71,6 +70,5 @@ Here's a few links to get you started with the migration: - [Migrate using the `cvs-fast-export` tool](https://gitlab.com/esr/cvs-fast-export) - [Stack Overflow post on importing the CVS repository](https://stackoverflow.com/a/11490134/974710) -- [Convert a CVS repository to Git](https://www.techrepublic.com/article/convert-cvs-repositories-to-git/) - [Man page of the `git-cvsimport` tool](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-cvsimport.html) - [Migrate using `reposurgeon`](http://www.catb.org/~esr/reposurgeon/repository-editing.html#conversion) diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index d9e03662434..692ec1390d2 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -1,7 +1,6 @@ --- -type: reference, howto stage: Manage -group: Import +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -16,10 +15,16 @@ The importer imports all of your cases and comments with the original case numbers and timestamps. You can also map FogBugz users to GitLab users. -Prerequisite: +## Prerequisites -- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was - [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. +> Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. + +- [FogBugz import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) + must be enabled. If not enabled, ask your GitLab administrator to enable it. The FogBugz import source is enabled + by default on GitLab.com. +- At least the Maintainer role on the destination group to import to. + +## Import project from FogBugz To import your project from FogBugz: diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 404bb4c8600..62cda62c2fe 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Import +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -8,15 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. -Import your projects from Gitea to GitLab with minimal effort. - -NOTE: -This requires Gitea `v1.0.0` or later. - -Prerequisite: - -- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was - [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. +Import your projects from Gitea to GitLab. The Gitea importer can import: @@ -30,13 +22,21 @@ The Gitea importer can import: When importing, repository public access is retained. If a repository is private in Gitea, it's created as private in GitLab as well. -## How it works - Because Gitea isn't an OAuth provider, author/assignee can't be mapped to users in your GitLab instance. This means the project creator (usually the user that started the import process) is set as the author. A reference, however, is kept on the issue about the original Gitea author. +## Prerequisites + +> Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. + +- Gitea version 1.0.0 or later. +- [Gitea import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) + must be enabled. If not enabled, ask your GitLab administrator to enable it. The Gitea import source is enabled + by default on GitLab.com. +- At least the Maintainer role on the destination group to import to. + ## Import your Gitea repositories The importer page is visible when you create a new project. @@ -75,10 +75,9 @@ From there, you can view the import statuses of your Gitea repositories: You also can: -- Import all of your Gitea projects in one go by selecting **Import all projects** - in the upper left corner. -- Filter projects by name. If filter is applied, selecting **Import all projects** - imports only matched projects. +- In the upper-left corner, select **Import all projects** to import all of your Gitea projects at once. +- Filter projects by name. If a filter is applied, **Import all projects** + imports only selected projects.  diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index eeebb5a166c..b2b1ede12d4 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -1,13 +1,14 @@ --- -type: reference, howto stage: Manage -group: Import +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your project from GitHub to GitLab **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388716) in GitLab 15.10, you no longer need to add any users to the parent group in GitLab to successfully import the **Require a pull request before merging - Allow specified actors to bypass required pull requests** branch protection rule. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378267) in GitLab 15.11, GitLab instances behind proxies no longer require `github.com` and `api.github.com` entries in the [allowlist for local requests](../../../security/webhooks.md#allow-outbound-requests-to-certain-ip-addresses-and-domains). You can import your GitHub projects from either GitHub.com or GitHub Enterprise. Importing projects does not migrate or import any types of groups or organizations from GitHub to GitLab. @@ -30,18 +31,19 @@ When importing projects: imported with a naming scheme similar to `GH-SHA-username/pull-request-number/fork-name/branch`. This may lead to a discrepancy in branches compared to those of the GitHub repository. -For additional technical details, refer to the [GitHub Importer](../../../development/github_importer.md) -developer documentation. - -For an overview of the import process, see the video [Migrating from GitHub to GitLab](https://youtu.be/VYOXuOg9tQI). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview of the import process, see [Migrating from GitHub to GitLab](https://youtu.be/VYOXuOg9tQI). ## Prerequisites +> Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. + To import projects from GitHub: -- You must have at least the Maintainer role on the destination group to import to. Using the Developer role for this - purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in - GitLab 16.0. +- [GitHub import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) + must be enabled. If not enabled, ask your GitLab administrator to enable it. The GitHub import source is enabled + by default on GitLab.com. +- You must have at least the Maintainer role on the destination group to import to. - Each GitHub author and assignee in the repository must have a [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) on GitHub that matches their GitLab email address (regardless of how the account was created). If their email address @@ -54,17 +56,18 @@ To import projects from GitHub: are properly mapped to the same user in GitLab. GitHub Enterprise does not require this field to be populated so you may have to add it on existing accounts. -See also [Branch protection rules and project settings](#branch-protection-rules-and-project-settings) for additional -prerequisites for those imports. +Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/383047), if you are using GitHub as an OmniAuth provider, ensure that the URL +perimeter is specified in the [OmniAuth configuration](../../../integration/github.md#enable-github-oauth-in-gitlab). ### Importing from GitHub Enterprise to self-managed GitLab If you are importing from GitHub Enterprise to a self-managed GitLab instance: - You must first enable the [GitHub integration](../../../integration/github.md). -- If GitLab is behind a HTTP/HTTPS proxy, you must populate the [allowlist for local requests](../../../security/webhooks.md#create-an-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). +- GitHub must be enabled as an import source in the + [Admin Area](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources). +- For GitLab 15.10 and earlier, you must add `github.com` and `api.github.com` entries in the + [allowlist for local requests](../../../security/webhooks.md#allow-outbound-requests-to-certain-ip-addresses-and-domains). ### Importing from GitHub.com to self-managed GitLab @@ -82,10 +85,9 @@ Before you begin, ensure that any GitHub user you want to map to a GitLab user h [publicly visible email address](https://docs.github.com/en/rest/users#get-a-user) on GitHub. If you are importing to GitLab.com, you can alternatively import GitHub repositories using a [personal access token](#use-a-github-token). -We do not recommend this method, as it does not associate all user activity (such as issues and pull requests) with matching GitLab users. -User-matching attempts occur in that order, and if a user is not identified either way, the activity is associated with -the user account that is performing the import. +If a GitHub user's public email address doesn't match any GitLab user email address, the user's activity is associated with the user account that is +performing the import. NOTE: If you are using a self-managed GitLab instance or if you are importing from GitHub Enterprise, this process requires that you have configured @@ -103,9 +105,7 @@ Prerequisite: - Authentication token with administrator access. -Using a personal access token to import projects is not recommended. If you are a GitLab.com user, -you can use a personal access token to import your project from GitHub, but this method cannot -associate all user activity (such as issues and pull requests) with matching GitLab users. +If you are a GitLab.com user, you can use a personal access token to import your project from GitHub. If you are an administrator of a self-managed GitLab instance or if you are importing from GitHub Enterprise, you cannot use a personal access token. The [GitHub integration method (above)](#use-the-github-integration) is recommended for all users. @@ -124,6 +124,21 @@ If you are not using the GitHub integration, you can still perform an authorizat To use a newer personal access token in imports after previously performing these steps, sign out of your GitLab account and sign in again, or revoke the older personal access token in GitHub. +### Filter repositories list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385113) in GitLab 16.0. + +After you authorize access to your GitHub repositories, GitLab redirects you to the importer page and +your GitHub repositories are listed. + +Use one of the following tabs to filter the list of repositories: + +- **Owner** (default): Filter the list to the repositories that you are the owner of. +- **Collaborated**: Filter the list to the repositories that you have contributed to. +- **Organization**: Filter the list to the repositories that belong to an organization you are a member of. + +When the **Organization** tab is selected, you can further narrow down your search by selecting an available GitHub organization from a dropdown. + ### Select additional items to import > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373705) in GitLab 15.5. @@ -140,15 +155,15 @@ You can choose to import these items, but this could significantly increase impo - **Import issue and pull request events**. - **Use alternative comments import method**. - **Import Markdown attachments**. +- **Import collaborators** (selected by default). Leaving it selected might result in new users using a seat in the group or namespace, + and being granted permissions [as high as project owner](#collaborators-members). Only direct collaborators are imported. + Outside collaborators are never imported. ### Select which repositories to import > - Ability to cancel pending or active imports [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247325) in GitLab 15.7. > - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. -After you have authorized access to your GitHub repositories, you are redirected to the GitHub importer page and -your GitHub repositories are listed. - By default, the proposed repository namespaces match the names as they exist in GitHub, but based on your permissions, you can choose to edit these names before you proceed to import any of them. @@ -170,6 +185,18 @@ Completed imports can be re-imported by selecting **Re-import** and specifying n  +### Check status of imports + +> Details of partially completed imports with a list of entities that failed to import [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386748) in GitLab 16.0. + +After imports are completed, they can be in one of three states: + +- **Completed**: GitLab imported all repository entities. +- **Partially completed**: GitLab failed to import some repository entities. +- **Failed**: GitLab imported no repository entities. + +Expand **Details** to see a list of [repository entities](#imported-data) that failed to import. + ## Mirror a repository and share pipeline status **(PREMIUM)** Depending on your GitLab tier, [repository mirroring](../repository/mirror/index.md) can be set up to keep @@ -209,17 +236,19 @@ The following items of a project are imported: - Repository description. - Git repository data. - Branch protection rules. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22650) in GitLab 15.4. +- Collaborators (members). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388716) in GitLab 15.10. From GitLab 16.0, can + be imported [as an additional item](#select-additional-items-to-import). - Issues. - Pull requests. - Wiki pages. - Milestones. - Labels. -- Release note descriptions. +- Release notes content. - Attachments for: - Release notes. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15620) in GitLab 15.4. - - Comments and notes. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18052) in GitLab 15.5. + - Comments. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18052) in GitLab 15.5. - Issue description. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18052) in GitLab 15.5. - - Merge Request description. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18052) in GitLab 15.5. + - Pull Request description. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18052) in GitLab 15.5. All attachment imports are disabled by default behind `github_importer_attachments_import` [feature flag](../../../administration/feature_flags.md). From GitLab 15.5, can @@ -232,7 +261,7 @@ The following items of a project are imported: - Pull request "merged by" information. - Pull request comments replies in discussions. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336596) in GitLab 14.5. -- Diff Notes suggestions. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340624) in GitLab 14.7. +- Pull request review comments suggestions. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340624) in GitLab 14.7. - Issue events and pull requests events. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7673) in GitLab 15.4 with `github_importer_issue_events_import` [feature flag](../../../administration/feature_flags.md) disabled by default. From GitLab 15.5, can be imported [as an additional item](#select-additional-items-to-import). The feature flag was @@ -252,14 +281,11 @@ When they are imported, supported GitHub branch protection rules are mapped to e | GitHub rule | GitLab rule | Introduced in | | :---------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ | | **Require conversation resolution before merging** for the project's default branch | **All threads must be resolved** [project setting](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/371110) | -| **Require a pull request before merging** | **No one** option in the **Allowed to push** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) | +| **Require a pull request before merging** | **No one** option in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) | | **Require signed commits** for the project's default branch | **Reject unsigned commits** GitLab [push rule](../repository/push_rules.md#prevent-unintended-consequences) **(PREMIUM)** | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) | | **Allow force pushes - Everyone** | **Allowed to force push** [branch protection setting](../protected_branches.md#allow-force-push-on-a-protected-branch) | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/370943) | | **Require a pull request before merging - Require review from Code Owners** | **Require approval from code owners** [branch protection setting](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) **(PREMIUM)** | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) | -| **Require a pull request before merging - Allow specified actors to bypass required pull requests** (1) | List of users in the **Allowed to push** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) **(PREMIUM)**. Without a Premium license, the list of users that are allowed to push is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) | - -1. To successfully import the **Require a pull request before merging - Allow specified actors to bypass required pull requests** rule, you must add to the parent group in GitLab - the users that are allowed to bypass required pull requests before you begin importing. +| **Require a pull request before merging - Allow specified actors to bypass required pull requests** | List of users in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) **(PREMIUM)**. Without a **Premium** subscription, the list of users that are allowed to push and merge is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) | Mapping GitHub rule **Require status checks to pass before merging** to [external status checks](../merge_requests/status_checks.md) was considered in issue @@ -267,39 +293,25 @@ Mapping GitHub rule **Require status checks to pass before merging** to into GitLab due to technical difficulties. You can still create [external status checks](../merge_requests/status_checks.md) manually. -## Alternative way to import notes and diff notes - -When GitHub Importer runs on extremely large projects not all notes & diff notes can be imported due to GitHub API `issues_comments` & `pull_requests_comments` endpoints limitation. -Not all pages can be fetched due to the following error coming from GitHub API: `In order to keep the API fast for everyone, pagination is limited for this resource. Check the rel=last link relation in the Link response header to see how far back you can traverse.`. - -An [alternative approach](#select-additional-items-to-import) for importing comments is available. - -Instead of using `issues_comments` and `pull_requests_comments`, use individual resources `issue_comments` and `pull_request_comments` instead to pull notes from one object at a time. -This allows us to carry over any missing comments, however it increases the number of network requests required to perform the import, which means its execution takes a longer time. +### Collaborators (members) -## Reduce GitHub API request objects per page +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388716) in GitLab 15.10. -Some GitHub API endpoints may return a 500 or 502 error for project imports from large repositories. -To reduce the chance of such errors, you can enable the feature flag -`github_importer_lower_per_page_limit` in the group project importing the data. This reduces the -page size from 100 to 50. +These GitHub collaborator roles are mapped to these GitLab [member roles](../../permissions.md#roles): -To enable this feature flag, start a [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session) -and run the following `enable` command: +| GitHub role | Mapped GitLab role | +|:------------|:-------------------| +| Read | Guest | +| Triage | Reporter | +| Write | Developer | +| Maintain | Maintainer | +| Admin | Owner | -```ruby -group = Group.find_by_full_path('my/group/fullpath') +GitHub Enterprise Cloud has +[custom repository roles](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-repository-roles). +These roles aren't supported and cause partially completed imports. -# Enable -Feature.enable(:github_importer_lower_per_page_limit, group) -``` - -To disable the feature, run this command: - -```ruby -# Disable -Feature.disable(:github_importer_lower_per_page_limit, group) -``` +To import GitHub collaborators, you must have at least the Write role on the GitHub project. Otherwise collaborators import is skipped. ## Import from GitHub Enterprise on an internal network @@ -443,3 +455,47 @@ repository to be imported manually. Administrators can manually import the repos # Trigger import from second step Gitlab::GithubImport::Stage::ImportRepositoryWorker.perform_async(project.id) ``` + +### Errors when importing large projects + +The GitHub importer might encounter some errors when importing large projects. + +#### Alternative way to import notes and diff notes + +When the GitHub importer runs on extremely large projects, not all notes and diff notes can be imported due to the GitHub API `issues_comments` and `pull_requests_comments` endpoint limitations. + +If it's not possible to fetch all pages, the GitHub API might return the following error: + +```plaintext +In order to keep the API fast for everyone, pagination is limited for this resource. Check the rel=last link relation in the Link response header to see how far back you can traverse. +``` + +An [alternative approach](#select-additional-items-to-import) for importing comments is available. + +Instead of using `issues_comments` and `pull_requests_comments`, use individual resources to pull notes from one object at a time. This way, you can carry over any missing comments. However, execution takes longer because this method increases the number of network requests required to perform the import. + +#### Reduce GitHub API request objects per page + +Some GitHub API endpoints might return a `500` or `502` error for project imports from large repositories. +To reduce the chance of these errors, in the group project importing the data, enable the +`github_importer_lower_per_page_limit` feature flag. When enabled, the flag reduces the +page size from `100` to `50`. + +To enable this feature flag: + +1. Start a [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session). +1. Run the following `enable` command: + + ```ruby + group = Group.find_by_full_path('my/group/fullpath') + + # Enable + Feature.enable(:github_importer_lower_per_page_limit, group) + ``` + +To disable the feature flag, run this command: + +```ruby +# Disable +Feature.disable(:github_importer_lower_per_page_limit, group) +``` diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index c00709d9697..2b69cd40fc7 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -1,39 +1,17 @@ --- -type: reference, howto stage: Manage -group: Import +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Import a project from GitLab.com to your self-managed GitLab instance (deprecated) **(FREE)** +# Import a project from GitLab.com to your self-managed GitLab instance (removed) **(FREE)** WARNING: The GitLab.com importer was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108502) in GitLab 15.8 -and will be removed in GitLab 16.0. To import GitLab projects from GitLab.com to a self-managed GitLab instance use +and removed in GitLab 16.0. To import GitLab projects from GitLab.com to a self-managed GitLab instance use [migrating groups and projects by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). -You can import your existing GitLab.com projects to your GitLab instance. - -Prerequisite: - -- GitLab.com integration must be enabled on your GitLab instance. - [Read more about GitLab.com integration for self-managed GitLab instances](../../../integration/gitlab.md). - -To import a GitLab.com project to your self-managed GitLab instance: - -1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. -1. Select **Import project**. -1. Select **GitLab.com**. -1. Give GitLab.com permission to access your projects. -1. Select **Import**. - -The importer imports your repository and issues. -When the importer is done, a new GitLab project is created with your imported data. - ## Related topics -- To automate user, group, and project import API calls, see - [Automate group and project import](index.md#automate-group-and-project-import). -- To import Wiki and merge request data to your new instance, - see [exporting a project](../settings/import_export.md#export-a-project-and-its-data). +- [Automate group and project import](index.md#automate-group-and-project-import) +- [Export a project](../settings/import_export.md#export-a-project-and-its-data) diff --git a/doc/user/project/import/img/bitbucket_import_select_project_v12_3.png b/doc/user/project/import/img/bitbucket_import_select_project_v12_3.png Binary files differdeleted file mode 100644 index bbc72a0b4b7..00000000000 --- a/doc/user/project/import/img/bitbucket_import_select_project_v12_3.png +++ /dev/null diff --git a/doc/user/project/import/img/fogbugz_import_finished.png b/doc/user/project/import/img/fogbugz_import_finished.png Binary files differdeleted file mode 100644 index 62c5c86c9b3..00000000000 --- a/doc/user/project/import/img/fogbugz_import_finished.png +++ /dev/null diff --git a/doc/user/project/import/img/manifest_status_v13_3.png b/doc/user/project/import/img/manifest_status_v13_3.png Binary files differdeleted file mode 100644 index c1a55ba1f50..00000000000 --- a/doc/user/project/import/img/manifest_status_v13_3.png +++ /dev/null diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 24748b2e89c..1265b8534d0 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -1,7 +1,6 @@ --- -type: reference, howto stage: Manage -group: Import +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -15,16 +14,11 @@ If you want to bring existing projects to GitLab or copy GitLab projects to a di - Between a self-managed instance and GitLab.com in both directions. - In the same GitLab instance. -Prerequisite: - -- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was - [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. - For any type of source and target, you can migrate GitLab projects: - When [migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended), which allows you to migrate all projects in a group simultaneously. Migrating projects by direct transfer is in - [Beta](../../../policy/alpha-beta-support.md#beta-features). The feature is not ready for production use. + [Beta](../../../policy/alpha-beta-support.md#beta). The feature is not ready for production use. - Using [file exports](../settings/import_export.md). With this method you can migrate projects one by one. No network connection between instances is required. @@ -32,13 +26,27 @@ If you only need to migrate Git repositories, you can [import each project by UR import issues and merge requests this way. To retain metadata like issues and merge requests, either: - [Migrate projects with groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). - This feature is in [Beta](../../../policy/alpha-beta-support.md#beta-features). It is not ready for production use. + This feature is in [Beta](../../../policy/alpha-beta-support.md#beta). It is not ready for production use. - Use [file exports](../settings/import_export.md) to import projects. Keep in mind the limitations of [migrating using file exports](../settings/import_export.md#items-that-are-exported). When migrating from self-managed to GitLab.com, user associations (such as comment author) are changed to the user who is importing the projects. +## Security + +Only import projects from sources you trust. If you import a project from an untrusted source, +an attacker could steal your sensitive data. For example, an imported project +with a malicious `.gitlab-ci.yml` file could allow an attacker to exfiltrate group CI/CD variables. + +GitLab self-managed administrators can reduce their attack surface by disabling import sources they don't need: + +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility and access controls**. +1. Scroll to **Import sources**. +1. Clear checkboxes for importers that are not required. + ## Available project importers You can import projects from: @@ -65,7 +73,7 @@ You can then [connect your external repository to get CI/CD benefits](../../../c GitLab can not automatically migrate Subversion repositories to Git. Converting Subversion repositories to Git can be difficult, but several tools exist including: -- [`git svn`](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Migrating-to-Git), for very small and simple repositories. +- [`git svn`](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Migrating-to-Git), for very small and basic repositories. - [`reposurgeon`](http://www.catb.org/~esr/reposurgeon/repository-editing.html), for larger and more complex repositories. ## Migrate using the API @@ -82,10 +90,9 @@ over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve an ## Migrate between two self-managed GitLab instances -To migrate from an existing self-managed GitLab instance to a new self-managed GitLab instance, it's -best to [back up](../../../raketasks/backup_restore.md) -the existing instance and restore it on the new instance. For example, this is useful when migrating -a self-managed instance from an old server to a new server. +To migrate from an existing self-managed GitLab instance to a new self-managed GitLab instance, +you should [back up](../../../raketasks/backup_restore.md) +the existing instance and restore it on the new instance. For example, you could use this method to migrate 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 @@ -109,7 +116,7 @@ To view project import history: 1. On the top bar, select **Create new...** (**{plus-square}**). 1. Select **New project/repository**. 1. Select **Import project**. -1. Select **History** in the upper right corner. +1. In the upper-right corner, select **History**. 1. If there are any errors for a particular import, you can see them by selecting **Details**. The history also includes projects created from [built-in](../index.md#create-a-project-from-a-built-in-template) @@ -154,8 +161,20 @@ GitLab from: For more information, see: +- Information on paid GitLab [migration services](https://about.gitlab.com/services/migration/). - [Quick Start](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate/-/blob/master/docs/using-congregate.md#quick-start). - [Frequently Asked Migration Questions](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate/-/blob/master/customer/famq.md), including settings that need checking afterwards and other limitations. For support, customers must enter into a paid engagement with GitLab Professional Services. + +## Troubleshooting + +### Imported repository is missing branches + +If an imported repository does not contain all branches of the source repository: + +1. Set the [environment variable](../../../administration/logs/index.md#override-default-log-level) `IMPORT_DEBUG=true`. +1. Retry the import with a [different group, subgroup, or project name](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#re-import-projects-from-external-providers). +1. If some branches are still missing, inspect [`importer.log`](../../../administration/logs/index.md#importerlog) + (for example, with [`jq`](../../../administration/logs/log_parsing.md#parsing-gitlab-railsimporterlog)). diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index c8b717d0421..ede9eb244c6 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -37,16 +37,10 @@ iterations of the GitLab Jira importer. ## Prerequisites -### Permissions - -To be able to import issues from a Jira project you must have read access on Jira -issues and at least the Maintainer role in the GitLab project that you wish to import into. - -### Jira integration - -This feature uses the existing GitLab [Jira integration](../../../integration/jira/index.md). - -Make sure you have the integration set up before trying to import Jira issues. +- To be able to import issues from a Jira project you must have read access on Jira + issues and at least the Maintainer role in the GitLab project that you wish to import into. +- This feature uses the existing GitLab [Jira integration](../../../integration/jira/index.md). + Make sure you have the integration set up before trying to import Jira issues. ## Import Jira issues to GitLab @@ -59,11 +53,11 @@ Importing large projects may take several minutes depending on the size of the i To import Jira issues to a GitLab project: -1. On the **{issues}** **Issues** page, select **Import Issues** (**{import}**) **> Import from Jira**. +1. On the **{issues}** **Issues** page, select **Actions** (**{ellipsis_v}**) **> Import from Jira**.  - The **Import from Jira** option is only visible if you have the [correct permissions](#permissions). + The **Import from Jira** option is only visible if you have the [correct permissions](#prerequisites). The following form appears. If you've previously set up the [Jira integration](../../../integration/jira/index.md), you can now see diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 514a6a0cb5a..7b3550d2dc9 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -1,7 +1,6 @@ --- -type: howto stage: Manage -group: Import +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -16,12 +15,16 @@ based on a manifest file like the one used by the Use the manifest to import a project with many repositories like the Android Open Source Project (AOSP). -## Requirements +## Prerequisites +> Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. + +- [Manifest import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) + must be enabled. If not enabled, ask your GitLab administrator to enable it. The Manifest import source is enabled + by default on GitLab.com. - GitLab must use PostgreSQL for its database, because [subgroups](../../group/subgroups/index.md) are needed for the manifest import to work. Read more about the [database requirements](../../../install/requirements.md#database). -- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was - [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. +- At least the Maintainer role on the destination group to import to. ## Manifest format diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index a96297b1a38..5f06daef0aa 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -1,7 +1,6 @@ --- -type: howto stage: Manage -group: Import +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -53,7 +52,7 @@ submit back from Git to Perforce. Here's a few links to get you started: - [`git-p4` manual page](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-p4.html) -- [`git-p4` example usage](https://git.wiki.kernel.org/index.php/Git-p4_Usage) +- [`git-p4` example usage](https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/Git-p4_Usage.html) - [Git book migration guide](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Migrating-to-Git#_perforce_import) `git p4` and `git filter-branch` are not very good at diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 8a2dbba1343..7b9615b883c 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -1,43 +1,11 @@ --- -type: howto stage: Manage -group: Import +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' --- -# Import Phabricator tasks into a GitLab project (deprecated) **(FREE SELF)** +# Import Phabricator tasks into a GitLab project (removed) **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/60562) in GitLab 12.0. - -WARNING: -The Phabricator task importer was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106369) in GitLab 15.7 -and will be removed in GitLab 16.0. - -WARNING: -The Phabricator task importer is in -[beta](../../../policy/alpha-beta-support.md#beta-features) and is -[**not** complete](https://gitlab.com/gitlab-org/gitlab/-/issues/284406). It imports -only an issue's title and description. The GitLab project created during the import -process contains only issues, and the associated repository is disabled. - -GitLab allows you to import all tasks from a Phabricator instance into -GitLab issues. The import creates a single project with the -repository disabled. - -Only the following basic fields are imported: - -- Title -- Description -- State (open or closed) -- Created at -- Closed at - -## Users - -The assignee and author of a user are deducted from a Task's owner and -author: If a user with the same username has access to the namespace -of the project being imported into, then the user is linked. - -## Enable this feature - -Enable Phabricator as an [import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) in the Admin Area. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106369) in GitLab 15.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117649) in 16.0. diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 93e3991ba19..4ad51ccb97f 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -1,18 +1,23 @@ --- -type: howto stage: Manage -group: Import +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import project from repository by URL **(FREE)** -Prerequisite: +You can import your existing repositories by providing the Git URL. -- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was - [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. +## Prerequisites -You can import your existing repositories by providing the Git URL: +> Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. + +- [Repository by URL import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) + must be enabled. If not enabled, ask your GitLab administrator to enable it. The Repository by URL import source is enabled + by default on GitLab.com. +- At least the Maintainer role on the destination group to import to. + +## Import project by URL 1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. 1. On the right of the page, select **New project**. diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md deleted file mode 100644 index c9abc0f459d..00000000000 --- a/doc/user/project/import/svn.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'index.md#import-from-subversion' -remove_date: '2023-03-15' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after <2023-03-15>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index 0a03513467e..da9d31e0ca8 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -1,8 +1,7 @@ --- stage: Manage -group: Import +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts --- # Migrate from TFVC to Git **(FREE)** diff --git a/doc/user/project/index.md b/doc/user/project/index.md index decf3b071e7..1512039fb25 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Organization +stage: Data Stores +group: Tenant Scale info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- @@ -139,9 +139,8 @@ Prerequisites: - You must have permission to add new projects to a namespace. To check if you have permission: 1. On the top bar, select **Main menu > Groups** and find your group. - 1. Confirm that **New project** is visible in the upper right - corner. Contact your GitLab - administrator if you require permission. + 1. In the upper-right corner, confirm that **New project** is visible. + Contact your GitLab administrator if you require permission. To push your repository and create a project: @@ -180,8 +179,6 @@ Your project's visibility is set to **Private** by default. To change project vi ## Related topics -- For a list of words that you cannot use as project names, see - [reserved project and group names](../../user/reserved_names.md). -- For a list of characters that you cannot use in project and group names, see - [limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names). -- [Manage projects](working_with_projects.md). +- [Reserved project and group names](../../user/reserved_names.md) +- [Limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names) +- [Manage projects](working_with_projects.md) diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md index 1b41dd0b669..633d565064c 100644 --- a/doc/user/project/integrations/apple_app_store.md +++ b/doc/user/project/integrations/apple_app_store.md @@ -1,19 +1,24 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Apple App Store **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104888) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `apple_app_store_integration`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104888) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `apple_app_store_integration`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385335) in GitLab 15.10. Feature flag `apple_app_store_integration` removed. -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 `apple_app_store_integration`. On GitLab.com, this feature is not available. +This feature is part of [Mobile DevOps](../../../ci/mobile_devops.md) developed by [GitLab Incubation Engineering](https://about.gitlab.com/handbook/engineering/incubation/). +The feature is still in development, but you can: -The Apple App Store integration makes it easy to configure your CI/CD pipelines to connect to [App Store Connect](https://appstoreconnect.apple.com) to build and release apps for iOS, iPadOS, macOS, tvOS, and watchOS. +- [Request a feature](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=feature_request). +- [Report a bug](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=report_bug). +- [Share feedback](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=general_feedback). -The integration is designed to be able to work out of the box with [fastlane](http://fastlane.tools/), but can be used with other build tools as well. +With the Apple App Store integration, you can configure your CI/CD pipelines to connect to [App Store Connect](https://appstoreconnect.apple.com) to build and release apps for iOS, iPadOS, macOS, tvOS, and watchOS. + +The Apple App Store integration works out of the box with [fastlane](https://fastlane.tools/). You can also use this integration with other build tools. ## Prerequisites @@ -29,16 +34,17 @@ GitLab supports enabling the Apple App Store integration at the project level. C 1. Select **Apple App Store**. 1. Turn on the **Active** toggle under **Enable Integration**. 1. Provide the Apple App Store Connect configuration information: - - **Issuer ID**: The Apple App Store Connect Issuer ID can be found in the *Keys* section under *Users and Access* the Apple App Store Connect portal. - - **Key ID**: The Key ID of the new private key that was just generated. - - **Private Key**: The Private Key that was just generated. Note: you are only be able to download this key one time. + - **Issuer ID**: The Apple App Store Connect issuer ID. + - **Key ID**: The key ID of the generated private key. + - **Private Key**: The generated private key. You can download this key only once. 1. Select **Save changes**. After the Apple App Store integration is activated: -- The global variables `$APP_STORE_CONNECT_API_KEY_ISSUER_ID`, `$APP_STORE_CONNECT_API_KEY_KEY_ID`, and `$APP_STORE_CONNECT_API_KEY_KEY` are created for CI/CD use. +- The global variables `$APP_STORE_CONNECT_API_KEY_ISSUER_ID`, `$APP_STORE_CONNECT_API_KEY_KEY_ID`, `$APP_STORE_CONNECT_API_KEY_KEY`, and `$APP_STORE_CONNECT_API_KEY_IS_KEY_CONTENT_BASE64` are created for CI/CD use. - `$APP_STORE_CONNECT_API_KEY_KEY` contains the Base64 encoded Private Key. +- `$APP_STORE_CONNECT_API_KEY_IS_KEY_CONTENT_BASE64` is always `true`. ## Security considerations @@ -48,12 +54,10 @@ Malicious code pushed to your `.gitlab-ci.yml` file could compromise your variab `$APP_STORE_CONNECT_API_KEY_KEY`, and send them to a third-party server. For more details, see [CI/CD variable security](../../../ci/variables/index.md#cicd-variable-security). -## fastlane Example +## Enable the integration in fastlane -Because this integration works out of the box with fastlane adding the code below to an app's `fastlane/Fastfile` activates the integration, and create the connection for any interactions with the Apple App Store uploading a Test Flight or public App Store release. +To enable the integration in fastlane and upload a TestFlight or public App Store release, you can add the following code to your app's `fastlane/Fastfile`: ```ruby -app_store_connect_api_key( - is_key_content_base64: true -) +app_store_connect_api_key ``` diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index 8bc1a984e3d..b1a4d2a2f78 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -1,12 +1,12 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Asana **(FREE)** -This integration adds commit messages as comments to Asana tasks. +The Asana integration adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, `https://app.asana.com/0/123456/987654`) or task IDs starting with `#` (for example, `#987654`). Every task ID found gets the commit comment added to it. diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 12039a70d0e..23990036f4e 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -125,7 +125,7 @@ For example: ### Builds not triggered If builds are not triggered, ensure you entered the right GitLab IP address in -Bamboo under **Trigger IP addresses**. Also check [service hook logs](index.md#troubleshooting-integrations) for request failures. +Bamboo under **Trigger IP addresses**. Also check [integration webhook logs](index.md#troubleshooting) for request failures. ### Advanced Atlassian Bamboo features not available in GitLab UI diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 2933203c593..f2af4dc6e4d 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -57,4 +57,4 @@ internal issue tracker, the internal issue is linked. ## Troubleshooting -To see recent service hook deliveries, check [service hook logs](index.md#troubleshooting-integrations). +For recent integration webhook deliveries, check [integration webhook logs](index.md#troubleshooting). diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 24a2e3d1ebc..b529d728e3b 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 0163bce3496..60b37f07bb5 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index c3134e986d3..7f8755f1114 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index c2371d32853..39dd548e7ca 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -1,12 +1,12 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Engineering Workflow Management (EWM) **(FREE)** -This integration allows you to go from GitLab to EWM work items mentioned in merge request +The EWM integration allows you to go from GitLab to EWM work items mentioned in merge request descriptions and commit messages. Each work item reference is automatically converted to a link to the work item. diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 990d0839581..3e75106a9bc 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -1,13 +1,13 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitHub **(PREMIUM)** You can update GitHub with pipeline status updates from GitLab. -This integration can help you if you use GitLab for CI/CD. +The GitHub integration can help you if you use GitLab for CI/CD.  diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 649b0c51818..fabdf07f76f 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -18,6 +18,10 @@ integrations on GitLab.com. ## Installation +In GitLab 15.0 and later, the GitLab for Slack app uses +[granular permissions](https://medium.com/slack-developer-blog/more-precision-less-restrictions-a3550006f9c3). +Although functionality has not changed, you should [reinstall the app](#update-the-gitlab-for-slack-app). + ### Through the Slack App Directory To enable the GitLab for Slack app for your workspace, @@ -43,8 +47,8 @@ To enable the GitLab integration for your Slack workspace: 1. Select **Install GitLab for Slack app**. 1. Select **Allow** on Slack's confirmation screen. -You can also select **Reinstall GitLab for Slack app** to update the app in your Slack workspace -to the latest version. See [Version history](#version-history) for details. +To update the app in your Slack workspace to the latest version, +you can also select **Reinstall GitLab for Slack app**. ## Slash commands @@ -63,6 +67,7 @@ Replace `<project>` with the project full path, or create a shorter [project ali | `/gitlab <project> issue comment <id> <shift+return> <comment>` | Adds a new comment with the comment body `<comment>` to the issue with the ID `<id>`. | | `/gitlab <project> deploy <from> to <to>` | [Deploys](#the-deploy-slash-command) from the `<from>` environment to the `<to>` environment. | | `/gitlab <project> run <job name> <arguments>` | Executes the [ChatOps](../../../ci/chatops/index.md) job `<job name>` on the default branch. | +| `/gitlab incident declare` | **Beta** Opens modal to [create a new incident](../../../operations/incident_management/slack.md). | ### The deploy slash command @@ -191,8 +196,3 @@ If you're not receiving notifications to a Slack channel, ensure: ### The App Home does not display properly If the [App Home](https://api.slack.com/start/overview#app_home) does not display properly, ensure your [app is up to date](#update-the-gitlab-for-slack-app). - -## Version history - -In GitLab 15.0 and later, the GitLab for Slack app is updated to [Slack's new granular permissions model](https://medium.com/slack-developer-blog/more-precision-less-restrictions-a3550006f9c3). -Although there is no change in functionality, you should [reinstall the app](#update-the-gitlab-for-slack-app). diff --git a/doc/user/project/integrations/google_play.md b/doc/user/project/integrations/google_play.md new file mode 100644 index 00000000000..2ae5a504e06 --- /dev/null +++ b/doc/user/project/integrations/google_play.md @@ -0,0 +1,55 @@ +--- +stage: Manage +group: Import and Integrate +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Google Play **(FREE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111621) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `google_play_integration`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/389611) in GitLab 15.11. Feature flag `google_play_integration` removed. + +This feature is part of [Mobile DevOps](../../../ci/mobile_devops.md) developed by [GitLab Incubation Engineering](https://about.gitlab.com/handbook/engineering/incubation/). +The feature is still in development, but you can: + +- [Request a feature](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=feature_request). +- [Report a bug](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=report_bug). +- [Share feedback](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=general_feedback). + +With the Google Play integration, you can configure your CI/CD pipelines to connect to the [Google Play Console](https://play.google.com/console) to build and release apps for Android devices. + +The Google Play integration works out of the box with [fastlane](https://fastlane.tools/). You can also use this integration with other build tools. + +## Enable the integration in GitLab + +Prerequisites: + +- You must have a [Google Play Console](https://play.google.com/console/developers) developer account. +- You must [generate a new service account key for your project](https://developers.google.com/android-publisher/getting_started) from the Google Cloud console. + +To enable the Google Play integration in GitLab: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Google Play**. +1. In **Enable integration**, select the **Active** checkbox. +1. In **Package name**, enter the package name of the app (for example, `com.gitlab.app_name`). +1. In **Service account key (.JSON)**, drag or upload your key file. +1. Select **Save changes**. + +After you enable the integration, the global variables `$SUPPLY_PACKAGE_NAME` and `$SUPPLY_JSON_KEY_DATA` are created for CI/CD use. + +### CI/CD variable security + +Malicious code pushed to your `.gitlab-ci.yml` file could compromise your variables, including `$SUPPLY_JSON_KEY_DATA`, and send them to a third-party server. For more information, see [CI/CD variable security](../../../ci/variables/index.md#cicd-variable-security). + +## Enable the integration in fastlane + +To enable the integration in fastlane and upload the build to the given track in Google Play, you can add the following code to your app's `fastlane/Fastfile`: + +```ruby +upload_to_play_store( + track: 'internal', + aab: '../build/app/outputs/bundle/release/app-release.aab' +) +``` diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 3537033902d..3470d11b983 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -1,13 +1,13 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Google Chat **(FREE)** -Integrate your project to send notifications from GitLab to a -room of your choice in [Google Chat](https://chat.google.com/) (former Google +You can configure your project to send notifications from GitLab to a +room of your choice in [Google Chat](https://chat.google.com/) (formerly Google Hangouts). ## Integration workflow @@ -28,7 +28,7 @@ notifications to Google Chat: To enable the integration in Google Chat: 1. Enter the room where you want to receive notifications from GitLab. -1. Open the room dropdown list in the upper left and select **Manage webhooks**. +1. In the upper-left corner, from the room dropdown list, select **Manage webhooks**. 1. Enter the name for your webhook, for example "GitLab integration". 1. Optional. Add an avatar for your bot. 1. Select **Save**. diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index 596821ba12b..4a586054aee 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -8,11 +8,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80999) in GitLab 14.9. -Use Harbor as the container registry for your GitLab project. +You can use Harbor as the container registry for your GitLab project. -[Harbor](https://goharbor.io/) is an open source registry that can help you manage artifacts across cloud-native compute platforms, like Kubernetes and Docker. +[Harbor](https://goharbor.io/) is an open-source registry that can help you manage artifacts across cloud-native compute platforms like Kubernetes and Docker. -This integration can help you if you need GitLab CI/CD and a container image repository. +The Harbor integration can help you if you need GitLab CI/CD and a container image repository. ## Prerequisites diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 57947e21736..f7019b2eeb2 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -72,13 +72,14 @@ You can configure the following integrations. | [Pipelines emails](pipeline_status_emails.md) | Send the pipeline status to a list of recipients by email. | **{dotted-circle}** No | | [Pivotal Tracker](pivotal_tracker.md) | Add commit messages as comments to Pivotal Tracker stories. | **{dotted-circle}** No | | [Prometheus](prometheus.md) | Monitor application metrics. | **{dotted-circle}** No | -| [Pumble](pumble.md) | Send event notifications to a Pumble channel. | **{dotted-circle}** No | +| [Pumble](pumble.md) | Send event notifications to a Pumble channel. | **{dotted-circle}** No | | Pushover | Get real-time notifications on your device. | **{dotted-circle}** No | | [Redmine](redmine.md) | Use Redmine as the issue tracker. | **{dotted-circle}** No | -| [Shimo Workspace](shimo.md) | Use Shimo instead of the GitLab Wiki. | **{dotted-circle}** No | +| [Shimo Workspace](shimo.md) | Use Shimo instead of the GitLab Wiki. | **{dotted-circle}** No | | [GitLab for Slack app](gitlab_slack_application.md) | Use Slack's official GitLab application. | **{dotted-circle}** No | | [Slack notifications](slack.md) | Send notifications about project events to Slack. | **{dotted-circle}** No | | [Slack slash commands](slack_slash_commands.md) | Enable slash commands in a workspace. | **{dotted-circle}** No | +| [Squash TM](squash_tm.md) | Update Squash TM requirements when GitLab issues are modified. | **{check-circle}** Yes | | [Unify Circuit](unify_circuit.md) | Send notifications about project events to Unify Circuit. | **{dotted-circle}** No | | [Webex Teams](webex_teams.md) | Receive events notifications. | **{dotted-circle}** No | | [YouTrack](youtrack.md) | Use YouTrack as the issue tracker. | **{dotted-circle}** No | @@ -102,9 +103,16 @@ supported by `push_hooks` and `tag_push_hooks` events aren't executed. You can change the number of supported branches or tags by changing the [`push_event_hooks_limit` application setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). -## Troubleshooting integrations +## Contribute to integrations + +If you're interested in developing a new native integration for GitLab, see: + +- [Integrations development guidelines](../../../development/integrations/index.md) +- [GitLab Developer Portal](https://developer.gitlab.com) + +## Troubleshooting -Some integrations use hooks to integrate with external applications. To confirm which ones use integration hooks, see the [available integrations](#available-integrations). For more information, see [Troubleshooting webhooks](webhooks.md#troubleshoot-webhooks). +Some integrations use hooks to integrate with external applications. To confirm which ones use integration hooks, see the [available integrations](#available-integrations). For more information, see [webhook troubleshooting](webhooks.md#troubleshooting). ### `Test Failed. Save Anyway` error @@ -114,7 +122,3 @@ push data to build the test payload, and there are no push events in the project To resolve this error, initialize the repository by pushing a test file to the project and set up the integration again. - -## Contribute to integrations - -To add a new integration, see the [Integrations development guide](../../../development/integrations/index.md). diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 23525c33e84..df11ed3e57c 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -1,13 +1,13 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # irker (IRC gateway) **(FREE)** -GitLab provides a way to push update messages to an irker server. When -configured, pushes to a project trigger the integration to send data directly +GitLab provides a way to push update messages to an irker server. After you configure +the integration, each push to a project triggers the integration to send data directly to the irker server. See also the [irker integration API documentation](../../../api/integrations.md). diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index fcc364724b7..a50d341c38e 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 192360f5440..3b5e4030487 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index fc5d4d3cc80..5d2c27fc2a4 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -58,4 +58,4 @@ GitLab to send the notifications: ## Related topics -- [Setting up an incoming webhook on Microsoft Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#setting-up-a-custom-incoming-webhook). +- [Setting up an incoming webhook on Microsoft Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#setting-up-a-custom-incoming-webhook) diff --git a/doc/user/project/integrations/mlflow_client.md b/doc/user/project/integrations/mlflow_client.md index bd14021ab1c..75fae4647d0 100644 --- a/doc/user/project/integrations/mlflow_client.md +++ b/doc/user/project/integrations/mlflow_client.md @@ -4,33 +4,31 @@ group: Incubation info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering program. No technical writer assigned to this group. --- -# MLFlow Client Integration **(FREE)** +# MLflow client integration **(FREE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.6 as an [Alpha](../../../policy/alpha-beta-support.md#alpha-features) release [with a flag](../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.11 as an [Experiment](../../../policy/alpha-beta-support.md#experiment) release [with a flag](../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. -DISCLAIMER: -MLFlow Client Integration is an experimental feature being developed by the Incubation Engineering Department, -and will receive significant changes over time. +NOTE: +Model experiment tracking is an [experimental feature](../../../policy/alpha-beta-support.md). +Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. -[MLFlow](https://mlflow.org/) is one of the most popular open source tools for Machine Learning Experiment Tracking. -GitLabs works as a backend to the MLFlow Client, [logging experiments](../ml/experiment_tracking/index.md). +[MLflow](https://mlflow.org/) is a popular open source tool for Machine Learning Experiment Tracking. +GitLab works as a backend to the MLflow Client, [logging experiments](../ml/experiment_tracking/index.md). Setting up your integrations requires minimal changes to existing code. -GitLab plays the role of proxy server, both for artifact storage and tracking data. It reflects the -MLFlow [Scenario 5](https://www.mlflow.org/docs/latest/tracking.html#scenario-5-mlflow-tracking-server-enabled-with-proxied-artifact-storage-access). +GitLab plays the role of a MLflow server. Running `mlflow server` is not necessary. -## Enable MLFlow Client Integration - -Complete this task to enable MLFlow Client Integration. +## Enable MLflow client integration Prerequisites: - A [personal access token](../../../user/profile/personal_access_tokens.md) for the project, with minimum access level of `api`. - The project ID. To find the project ID, on the top bar, select **Main menu > Projects** and find your project. On the left sidebar, select **Settings > General**. -1. Set the tracking URI and token environment variables on the host that runs the code (your local environment, CI pipeline, or remote host). +To enable MLflow client integration: - For example: +1. Set the tracking URI and token environment variables on the host that runs the code. + This can be your local environment, CI pipeline, or remote host. For example: ```shell export MLFLOW_TRACKING_URI="http://<your gitlab endpoint>/api/v4/projects/<your project id>/ml/mlflow" @@ -39,43 +37,66 @@ Prerequisites: 1. If your training code contains the call to `mlflow.set_tracking_uri()`, remove it. -When running the training code, MLFlow will create experiments, runs, log parameters, metrics, +When running the training code, MLflow creates experiments, runs, log parameters, metrics, metadata and artifacts on GitLab. -After experiments are logged, they are listed under `/<your project>/-/ml/experiments`. Runs are registered as Model Candidates, -that can be explored by selecting an experiment. +After experiments are logged, they are listed under `/<your project>/-/ml/experiments`. +Runs are registered as: + +- Model Candidates, which can be explored by selecting an experiment. +- Tags, which are registered as metadata. + +## Associating a candidate to a CI/CD job + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119454) in GitLab 16.1. + +If your training code is being run from a CI/CD job, GitLab can use that information to enhance +candidate metadata. To do so, add the following snippet to your training code within the run +execution context: + +```python +with mlflow.start_run(run_name=f"Candidate {index}"): + # Your training code + + # Start of snippet to be included + if os.getenv('GITLAB_CI'): + mlflow.set_tag('gitlab.CI_JOB_ID', os.getenv('CI_JOB_ID')) + # End of snippet to be included +``` + +## Supported MLflow client methods and caveats + +GitLab supports these methods from the MLflow client. Other methods might be supported but were not +tested. More information can be found in the [MLflow Documentation](https://www.mlflow.org/docs/1.28.0/python_api/mlflow.html). + +| Method | Supported | Version Added | Comments | +|--------------------------|------------------|----------------|----------| +| `get_experiment` | Yes | 15.11 | | +| `get_experiment_by_name` | Yes | 15.11 | | +| `set_experiment` | Yes | 15.11 | | +| `get_run` | Yes | 15.11 | | +| `start_run` | Yes | 15.11 | | +| `log_artifact` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty string. Does not support directories. +| `log_artifacts` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty string. Does not support directories. +| `log_batch` | Yes | 15.11 | | +| `log_metric` | Yes | 15.11 | | +| `log_metrics` | Yes | 15.11 | | +| `log_param` | Yes | 15.11 | | +| `log_params` | Yes | 15.11 | | +| `log_figure` | Yes | 15.11 | | +| `log_image` | Yes | 15.11 | | +| `log_text` | Yes with caveat | 15.11 | (15.11) Does not support directories. +| `log_dict` | Yes with caveat | 15.11 | (15.11) Does not support directories. +| `set_tag` | Yes | 15.11 | | +| `set_tags` | Yes | 15.11 | | +| `set_terminated` | Yes | 15.11 | | +| `end_run` | Yes | 15.11 | | +| `update_run` | Yes | 15.11 | | +| `log_model` | Partial | 15.11 | (15.11) Saves the artifacts, but not the model data. `artifact_path` must be empty. ## Limitations -- The API GitLab supports is the one defined at MLFlow version 1.28.0. +- The API GitLab supports is the one defined at MLflow version 1.28.0. - API endpoints not listed above are not supported. -- During creation of experiments and runs, tags are ExperimentTags and RunTags are stored, even though they are not displayed. -- MLFlow Model Registry is not supported. - -## Supported methods and caveats - -This is a list of methods we support from the MLFlow client. Other methods might be supported but were not -tested. More information can be found in the [MLFlow Documentation](https://www.mlflow.org/docs/1.28.0/python_api/mlflow.html). - -### `set_experiment()` - -Accepts both `experiment_name` and `experiment_id` - -### `start_run()` - -- Nested runs have not been tested. -- `run_name` is not supported - -### `log_param()`, `log_params()`, `log_metric()`, `log_metrics()` - -Work as defined by the documentation - -### `log_artifact()`, `log_artifacts()` - -`artifact_path` must be empty string. - -### `log_model()` - -This is an experimental method in MLFlow, and partial support is offered. It stores the model artifacts, but does -not log the model information. The `artifact_path` parameter must be set to `''`, because Generic Packages do not support folder -structure. +- During creation of experiments and runs, ExperimentTags are stored, even though they are not displayed. +- MLflow Model Registry is not supported. diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index ae1737f8d3f..da09d621d07 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -9,12 +9,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w NOTE: This integration only appears if you're in a [development environment](https://gitlab.com/gitlab-org/gitlab-mock-ci-service#setup-mockci-integration). -To set up the mock CI service server, respond to the following endpoints +To set up the mock CI service server, respond to the following endpoints: - `commit_status`: `#{project.namespace.path}/#{project.path}/status/#{sha}.json` - - Have your service return `200 { status: ['failed'|'canceled'|'running'|'pending'|'success'|'success-with-warnings'|'skipped'|'not_found'] }` - - If the service returns a 404, it is interpreted as `pending` + - Have your service return `200 { status: ['failed'|'canceled'|'running'|'pending'|'success'|'success-with-warnings'|'skipped'|'not_found'] }`. + - If the service returns a 404, the service is interpreted as `pending`. - `build_page`: `#{project.namespace.path}/#{project.path}/status/#{sha}` - - Just where the build is linked to, doesn't matter if implemented + - Where the build is linked to (whether or not it's implemented). -For an example of a mock CI server, see [`gitlab-org/gitlab-mock-ci-service`](https://gitlab.com/gitlab-org/gitlab-mock-ci-service) +For an example of a mock CI server, see [`gitlab-org/gitlab-mock-ci-service`](https://gitlab.com/gitlab-org/gitlab-mock-ci-service). diff --git a/doc/user/project/integrations/pipeline_status_emails.md b/doc/user/project/integrations/pipeline_status_emails.md index 009bb6662ff..9a87b5b3110 100644 --- a/doc/user/project/integrations/pipeline_status_emails.md +++ b/doc/user/project/integrations/pipeline_status_emails.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index 034be8ab3d8..e1d48037ba8 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -1,12 +1,12 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pivotal Tracker **(FREE)** -This integration adds commit messages as comments to Pivotal Tracker stories. +The Pivotal Tracker integration adds commit messages as comments to Pivotal Tracker stories. Once enabled, commit messages are checked for square brackets containing a hash mark followed by the story ID (for example, `[#555]`). Every story ID found gets the commit comment added to it. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index cd92e49cada..d17e8e6bfca 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -2,129 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: 'index.md' --- -# Prometheus **(FREE)** +# Prometheus (removed) **(FREE)** -GitLab offers powerful integration with [Prometheus](https://prometheus.io) for -monitoring key metrics of your apps, directly in GitLab. -Metrics for each environment are retrieved from Prometheus, and then displayed -in the GitLab interface. - - - -There are two ways to set up Prometheus integration, depending on where your apps are running: - -- For deployments on Kubernetes, GitLab can be [integrated with an in-cluster Prometheus](#prometheus-cluster-integration) -- For other deployment targets, [specify the Prometheus server](#manual-configuration-of-prometheus). - -Once enabled, GitLab detects metrics from known services in the -[metric library](prometheus_library/index.md). You can also -[add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create -[custom dashboards](../../../operations/metrics/dashboards/index.md). - -## Enabling Prometheus Integration - -### Prometheus cluster integration - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55244) in GitLab 13.11. -> - [Replaced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62725) the Prometheus cluster applications in GitLab 14.0. - -GitLab can query an in-cluster Prometheus for your metrics. -See [Prometheus cluster integration](../../clusters/integrations.md#prometheus-cluster-integration) for details. - -### Manual configuration of Prometheus - -#### Requirements - -Integration with Prometheus requires the following: - -- Prometheus must be configured to collect one of the [supported metrics](prometheus_library/index.md) -- Each metric must have a label to indicate the environment -- GitLab must have network connectivity to the Prometheus server - -#### Getting started - -Installing and configuring Prometheus to monitor applications is fairly straightforward. - -1. [Install Prometheus](https://prometheus.io/docs/prometheus/latest/installation/) -1. Set up one of the [supported monitoring targets](prometheus_library/index.md) -1. Configure the Prometheus server to - [collect their metrics](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) - -#### Configuration in GitLab - -The actual configuration of Prometheus integration in GitLab -requires the domain name or IP address of the Prometheus server you'd like -to integrate with. If the Prometheus resource is secured with Google's Identity-Aware Proxy (IAP), -you can pass information like Client ID and Service Account credentials. -GitLab can use these to access the resource. More information about authentication from a -service account can be found at Google's documentation for -[Authenticating from a service account](https://cloud.google.com/iap/docs/authentication-howto#authenticating_from_a_service_account). - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. -1. Select **Prometheus**. -1. For **API URL**, provide the domain name or IP address of your server, such as - `http://prometheus.example.com/` or `http://192.0.2.1/`. -1. (Optional) In **Google IAP Audience Client ID**, provide the Client ID of the - Prometheus OAuth Client secured with Google IAP. -1. (Optional) In **Google IAP Service Account JSON**, provide the contents of the - Service Account credentials file that is authorized to access the Prometheus resource. - The JSON key `token_credential_uri` is discarded to prevent - [Server-side Request Forgery (SSRF)](https://www.hackerone.com/application-security/how-server-side-request-forgery-ssrf). -1. Select **Save changes**. - - - -#### Thanos configuration in GitLab - -You can configure [Thanos](https://thanos.io/) as a drop-in replacement for Prometheus -with GitLab. Use the domain name or IP address of the Thanos server you'd like -to integrate with. - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. -1. Select **Prometheus**. -1. Provide the domain name or IP address of your server, for example - `http://thanos.example.com/` or `http://192.0.2.1/`. -1. Select **Save changes**. - -### Precedence with multiple Prometheus configurations - -Although you can enable both a [manual configuration](#manual-configuration-of-prometheus) -and [cluster integration](#prometheus-cluster-integration) of Prometheus, you -can use only one: - -- If you have enabled a - [Prometheus manual configuration](#manual-configuration-of-prometheus) - and a [Prometheus cluster integration](#prometheus-cluster-integration), - the manual configuration takes precedence and is used to run queries from - [custom dashboards](../../../operations/metrics/dashboards/index.md) and - [custom metrics](../../../operations/metrics/index.md#adding-custom-metrics). -- If you have managed Prometheus applications installed on Kubernetes clusters - at **different** levels (project, group, instance), the order of precedence is described in - [Cluster precedence](../../instance/clusters/index.md#cluster-precedence). -- If you have managed Prometheus applications installed on multiple Kubernetes - clusters at the **same** level, the Prometheus application of a cluster with a - matching [environment scope](../../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) is used. - -## Determining the performance impact of a merge - -Developers can view the performance impact of their changes in the merge -request workflow. This feature requires [Kubernetes](prometheus_library/kubernetes.md) metrics. - -When a source branch has been deployed to an environment, a sparkline and -numeric comparison of the average memory consumption displays. On the -sparkline, a dot indicates when the current changes were deployed, with up to 30 minutes of -performance data displayed before and after. The comparison shows the difference -between the 30 minute average before and after the deployment. This information -is updated after each commit has been deployed. - -Once merged and the target branch has been redeployed, the metrics switches -to show the new environments this revision has been deployed to. - -Performance data is available for the duration it is persisted on the -Prometheus server. - - +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 1e9319fa7c7..848ccbb85f6 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -2,48 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../../../operations/index.md' --- -# Monitoring AWS resources (DEPRECATED) **(FREE)** +# Monitoring AWS resources (removed) **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -in GitLab 14.7, and is planned for removal in GitLab 16.0. - -GitLab supports automatically detecting and monitoring AWS resources, starting -with the [Elastic Load Balancer](https://aws.amazon.com/elasticloadbalancing/) (ELB). -This is provided by leveraging the official [Cloudwatch exporter](https://github.com/prometheus/cloudwatch_exporter), which translates [Cloudwatch metrics](https://aws.amazon.com/cloudwatch/) into -a Prometheus readable form. - -## Requirements - -You must enable the [Prometheus service](../prometheus.md). - -## Supported metrics - -| Name | Query | -|----------------------|-------| -| Throughput (req/sec) | `sum(aws_elb_request_count_sum{%{environment_filter}}) / 60` | -| Latency (ms) | `avg(aws_elb_latency_average{%{environment_filter}}) * 1000` | -| HTTP Error Rate (%) | `sum(aws_elb_httpcode_backend_5_xx_sum{%{environment_filter}}) / sum(aws_elb_request_count_sum{%{environment_filter}})` | - -## Configuring Prometheus to monitor for Cloudwatch metrics - -To get started with Cloudwatch monitoring, install and configure the -[Cloudwatch exporter](https://github.com/prometheus/cloudwatch_exporter). The -Cloudwatch exporter retrieves and parses the specified Cloudwatch metrics, and -translates them into a Prometheus monitoring endpoint. - -The only supported AWS resource is the Elastic Load Balancer, whose Cloudwatch -metrics are listed in [this AWS documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html). - -You can [download a sample Cloudwatch Exporter configuration file](../samples/cloudwatch.yml) -that's configured for basic AWS ELB monitoring. - -## Specifying the Environment label - -To isolate and display only the relevant metrics for a given environment, -GitLab needs a method to detect which labels are associated. To do this, GitLab -[looks for an `environment` label](index.md#identifying-environments). +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index b4533d83acd..ca015d7dc8a 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -2,34 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../../../operations/index.md' --- -# Monitoring HAProxy (DEPRECATED) **(FREE)** +# Monitoring HAProxy (removed) **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -in GitLab 14.7, and is planned for removal in GitLab 16.0. - -GitLab has support for automatically detecting and monitoring HAProxy. This is provided by leveraging the [HAProxy Exporter](https://github.com/prometheus/haproxy_exporter), which translates HAProxy statistics into a Prometheus readable form. - -## Requirements - -The [Prometheus service](../prometheus.md) must be enabled. - -## Metrics supported - -| Name | Query | -| ---- | ----- | -| Throughput (req/sec) | `sum(rate(haproxy_frontend_http_requests_total{%{environment_filter}}[2m])) by (code)` | -| HTTP Error Rate (%) | `sum(rate(haproxy_frontend_http_requests_total{code="5xx",%{environment_filter}}[2m])) / sum(rate(haproxy_frontend_http_requests_total{%{environment_filter}}[2m]))` | - -## Configuring Prometheus to monitor for HAProxy metrics - -To get started with NGINX monitoring, you should install and configure the [HAProxy exporter](https://github.com/prometheus/haproxy_exporter) which parses these statistics and translates them into a Prometheus monitoring endpoint. - -## Specifying the Environment label - -In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index afefe80271e..ee0b0d1fccb 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -2,43 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../../../operations/index.md' --- -# Prometheus Metrics library (DEPRECATED) **(FREE)** +# Prometheus Metrics library (removed) **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -in GitLab 14.7, and is planned for removal in GitLab 16.0. - -GitLab offers automatic detection of select [Prometheus exporters](https://prometheus.io/docs/instrumenting/exporters/). - -## Exporters - -Currently supported exporters are: - -- [Kubernetes](kubernetes.md) -- [NGINX](nginx.md) -- [NGINX Ingress Controller 0.9.0-0.15.x](nginx_ingress_vts.md) -- [NGINX Ingress Controller 0.16.0+](nginx_ingress.md) -- [HAProxy](haproxy.md) -- [Amazon Cloud Watch](cloudwatch.md) - -We have tried to surface the most important metrics for each exporter, and -continue to add support for additional exporters in future releases. If you -would like to add support for other official exporters, contributions are welcome. - -## Identifying Environments - -GitLab retrieves performance data from the configured Prometheus server, and -attempts to identifying the presence of known metrics. Once identified, GitLab -then needs to be able to map the data to a particular environment. - -To isolate and only display relevant metrics for a given environment, -GitLab needs a method to detect which labels are associated. To do that, -GitLab uses the defined queries and fills in the environment specific variables. -Typically this involves looking for the -[`$CI_ENVIRONMENT_SLUG`](../../../../ci/variables/index.md#predefined-cicd-variables), -but may also include other information such as the project's Kubernetes namespace. -Each search query is defined in the [exporter specific documentation](#exporters). +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 34a6823f007..4b8b9b4bc21 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -2,66 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../../../operations/index.md' --- -# Monitoring Kubernetes (DEPRECATED) **(FREE)** +# Monitoring Kubernetes (removed) **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -in GitLab 14.7, and is planned for removal in GitLab 16.0. - -GitLab has support for automatically detecting and monitoring Kubernetes metrics. - -## Requirements - -The [Prometheus](../prometheus.md) and [Kubernetes](../../../infrastructure/clusters/index.md) -integration services must be enabled. - -## Metrics supported - -- Average Memory Usage (MB): - - ```prometheus - avg(sum(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}) by (job)) without (job) / count(avg(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}) without (job)) /1024/1024 - ``` - -- Average CPU Utilization (%): - - ```prometheus - avg(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}[15m])) by (job)) without (job) / count(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}[15m])) by (pod_name)) - ``` - -## Configuring Prometheus to monitor for Kubernetes metrics - -Prometheus needs to be deployed into the cluster and configured properly to gather Kubernetes metrics. GitLab supports two methods for doing so: - -- GitLab [integrates with Kubernetes](../../clusters/index.md), and can [query a Prometheus in a connected cluster](../../../clusters/integrations.md#prometheus-cluster-integration). The in-cluster Prometheus can be configured to automatically collect application metrics from your cluster. -- To configure your own Prometheus server, you can follow the [Prometheus documentation](https://prometheus.io/docs/introduction/overview/). - -## Specifying the Environment - -To isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available. - -Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/index.md#predefined-cicd-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. - -## Displaying Canary metrics **(PREMIUM)** - -GitLab also gathers Kubernetes metrics for [canary deployments](../../canary_deployments.md), allowing easy comparison between the current deployed version and the canary. - -These metrics expect the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name to begin with `$CI_ENVIRONMENT_SLUG-canary`, to isolate the canary metrics. - -### Canary metrics supported - -- Average Memory Usage (MB) - - ```prometheus - avg(sum(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}) by (job)) without (job) / count(avg(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}) without (job)) /1024/1024 - ``` - -- Average CPU Utilization (%) - - ```prometheus - avg(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}[15m])) by (job)) without (job) / count(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}[15m])) by (pod_name)) - ``` +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index f0a3b25f11a..995de6a28f3 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -2,42 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../../../operations/index.md' --- -# Monitoring NGINX (DEPRECATED) **(FREE)** +# Monitoring NGINX (removed) **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -in GitLab 14.7, and is planned for removal in GitLab 16.0. - -GitLab has support for automatically detecting and monitoring NGINX. This is provided by leveraging the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter), which translates [VTS statistics](https://github.com/vozlt/nginx-module-vts) into a Prometheus readable form. - -## Requirements - -The [Prometheus service](../prometheus.md) must be enabled. - -## Metrics supported - -NGINX server metrics are detected, which tracks the pages and content directly served by NGINX. - -[`environment_filter`](../../../../operations/metrics/dashboards/variables.md#environment_filter) is one of the predefined variables that metrics dashboards support. - -| Name | Query | -| ---- | ----- | -| Throughput (req/sec) | `sum(rate(nginx_server_requests{server_zone!="*", server_zone!="_", %{environment_filter}}[2m])) by (code)` | -| Latency (ms) | `avg(nginx_server_requestMsec{%{environment_filter}})` | -| HTTP Error Rate (HTTP Errors / sec) | `sum(rate(nginx_server_requests{code="5xx", %{environment_filter}}[2m]))` | -| HTTP Error (%)| `sum(rate(nginx_server_requests{code=~"5.*", host="*", %{environment_filter}}[2m])) / sum(rate(nginx_server_requests{code="total", host="*", %{environment_filter}}[2m])) * 100` | - -## Configuring Prometheus to monitor for NGINX metrics - -To get started with NGINX monitoring, you should first enable the [VTS statistics](https://github.com/vozlt/nginx-module-vts) module for your NGINX server. This captures and displays statistics in an HTML readable form. Next, you should install and configure the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter) which parses these statistics and translates them into a Prometheus monitoring endpoint. - -If you are using NGINX as your Kubernetes Ingress, GitLab [automatically detects](nginx_ingress.md) the metrics once enabled in 0.9.0 and later releases. - -## Specifying the Environment label - -In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index 947210541f4..03f88e6f7c5 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -2,48 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../../../operations/index.md' --- -# Monitoring NGINX Ingress Controller (DEPRECATED) **(FREE)** +# Monitoring NGINX Ingress Controller (removed) **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -in GitLab 14.7, and is planned for removal in GitLab 16.0. - -GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the built-in Prometheus metrics included with Kubernetes NGINX Ingress controller [version 0.16.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0160) onward. - -NOTE: -NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics exporter](nginx_ingress_vts.md), which exports metrics different than the built-in metrics. - -## Requirements - -[Prometheus integration](../prometheus.md) must be active. - -## Metrics supported - -| Name | Query | -| ---- | ----- | -| Throughput (req/sec) | `sum(label_replace(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m]), "status_code", "${1}xx", "status", "(.)..")) by (status_code)` | -| Latency (ms) | `sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_sum{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_count{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 1000` | -| HTTP Error Rate (%) | `sum(rate(nginx_ingress_controller_requests{status=~"5.*",namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 100` | - -## Configuring NGINX Ingress monitoring - -Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint starts running on port 10254. - -Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: - -- `prometheus.io/scrape: "true"` -- `prometheus.io/port: "10254"` - -Managing these settings depends on how NGINX Ingress has been deployed. If you have deployed via the [official Helm chart](https://github.com/kubernetes/ingress-nginx/tree/master/charts/ingress-nginx), metrics can be enabled with `controller.stats.enabled` along with the required annotations. Alternatively it is possible to edit the NGINX Ingress YAML directly in the [Kubernetes dashboard](https://github.com/kubernetes/dashboard). - -## Specifying the Environment label - -To isolate and display only relevant metrics for a given environment, GitLab needs a method to -detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. -In this case, the `ingress` label must include the value `<CI_ENVIRONMENT_SLUG>`. - -If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index f8057866592..837be9d1e0a 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -2,46 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../../../operations/index.md' --- -# Monitoring NGINX Ingress Controller with VTS metrics (DEPRECATED) **(FREE)** +# Monitoring NGINX Ingress Controller with VTS metrics (removed) **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -in GitLab 14.7, and is planned for removal in GitLab 16.0. - -NOTE: -[NGINX Ingress version 0.16](nginx_ingress.md) and above have built-in Prometheus metrics, which are different than the VTS based metrics. - -GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the included VTS Prometheus metrics exporter in [version 0.9.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#09-beta1) through [0.15.x](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0150). - -## Requirements - -[Prometheus integration](../prometheus.md) must be active. - -## Metrics supported - -| Name | Query | -| ---- | ----- | -| Throughput (req/sec) | `sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) by (status_code)` | -| Latency (ms) | `avg(nginx_upstream_response_msecs_avg{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"})` | -| HTTP Error Rate (%) | `sum(rate(nginx_upstream_responses_total{status_code="5xx", upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) / sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) * 100` | - -## Configuring NGINX Ingress monitoring - -Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) has built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint begins running on port 10254. - -Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: - -- `prometheus.io/scrape: "true"` -- `prometheus.io/port: "10254"` - -Managing these settings depends on how NGINX Ingress has been deployed. If you have deployed via the [official Helm chart](https://github.com/kubernetes/ingress-nginx/tree/master/charts/ingress-nginx), metrics can be enabled with `controller.stats.enabled` along with the required annotations. Alternatively it is possible edit the NGINX Ingress YAML directly in the [Kubernetes dashboard](https://github.com/kubernetes/dashboard). - -## Specifying the Environment label - -To isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. - -If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/pumble.md b/doc/user/project/integrations/pumble.md index f9c0c79be1b..e05ff9489ca 100644 --- a/doc/user/project/integrations/pumble.md +++ b/doc/user/project/integrations/pumble.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index 0a399d3481f..df8a6681e2b 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -1,13 +1,12 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Redmine **(FREE)** -Use [Redmine](https://www.redmine.org/) as the issue tracker. - +You can use [Redmine](https://www.redmine.org/) as an external issue tracker. To enable the Redmine integration in a project: 1. On the top bar, select **Main menu > Projects** and find your project. diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index a34655c8e35..a0beb71d83f 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -9,6 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w ServiceNow offers several integrations to help centralize and automate your management of GitLab workflows. +To simplify your stack and streamline your processes, you should use GitLab [deployment approvals](../../../ci/environments/deployment_approvals.md) whenever possible. + ## GitLab spoke With the GitLab spoke in ServiceNow, you can automate actions for GitLab diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md index ca09de06dc6..cf9745929a1 100644 --- a/doc/user/project/integrations/shimo.md +++ b/doc/user/project/integrations/shimo.md @@ -1,10 +1,10 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -<!--- start_remove The following content will be removed on remove_date: '2023-05-22' --> +<!--- start_remove The following content will be removed on remove_date: '2023-08-22' --> # Shimo (deprecated) **(FREE)** diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 09e7189d4f5..5b769b84663 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -1,16 +1,18 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- +<!--- start_remove The following content will be removed on remove_date: '2024-05-22' --> -# Slack notifications **(FREE)** +# Slack notifications (deprecated) **(FREE)** WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/372411) on GitLab.com -in GitLab 15.9 and is [planned for removal](https://gitlab.com/groups/gitlab-org/-/epics/8673). -For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) instead. -For self-managed GitLab instances, you can continue to use this feature. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/372411) in GitLab 15.9 +and is planned for removal in 17.0. Use the [GitLab for Slack app](gitlab_slack_application.md) instead. +This change is a breaking change. +For the planned support of the GitLab for Slack app for self-managed instances, +see [epic 1211](https://gitlab.com/groups/gitlab-org/-/epics/1211). The Slack notifications integration enables your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up @@ -125,7 +127,7 @@ To view which of these problems is the cause of the issue: ``` If GitLab does not trust HTTPS connections to itself, -[add your certificate to the GitLab trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +[add your certificate to the GitLab trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates). If GitLab does not trust connections to Slack, the GitLab OpenSSL trust store is incorrect. Typical causes are: @@ -150,3 +152,5 @@ p.each do |project| project.slack_integration.update!(:active, false) end ``` + +<!--- end_remove --> diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 2563cec2b05..4fa4b75422e 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -15,7 +15,7 @@ working in Slack, you can use Slack slash commands. To use Slack slash commands, you must configure both Slack and GitLab. GitLab can also send events (for example, `issue created`) to Slack as notifications. -The [Slack notifications service](slack.md) is configured separately. +The [Slack notifications integration](slack.md) is configured separately. ## Configure GitLab and Slack diff --git a/doc/user/project/integrations/squash_tm.md b/doc/user/project/integrations/squash_tm.md new file mode 100644 index 00000000000..2a1106edb0c --- /dev/null +++ b/doc/user/project/integrations/squash_tm.md @@ -0,0 +1,37 @@ +--- +stage: Manage +group: Import and Integrate +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Squash TM **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337855) in GitLab 15.10. + +When [Squash TM](https://www.squashtest.com/squash-gitlab-integration?lang=en) (Test Management) +integration is enabled and configured in GitLab, issues (typically user stories) created in GitLab +are synchronized as requirements in Squash TM and test progress is reported in GitLab issues. + +## Configure Squash TM + +1. Optional. Ask your system administrator to [configure a token in the properties file](https://tm-en.doc.squashtest.com/latest/redirect/gitlab-integration-token.html). +1. Follow the [Squash TM documentation](https://tm-en.doc.squashtest.com/latest/redirect/gitlab-integration-configuration.html) to: + 1. Create a GitLab server. + 1. Enable the `Xsquash4GitLab` plugin + 1. Configure a synchronization. + 1. From the **Real-time synchronization** panel, copy the following fields to use later in GitLab: + + - **Webhook URL**. + - **Secret token** if your Squash TM system administrator configured one at step 1. + +## Configure GitLab + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Squash TM**. +1. Ensure that the **Active** toggle is enabled. +1. In the **Trigger** section, indicate which type of issue is concerned by the real-time synchronization. +1. Complete the fields: + + - Enter the **Squash TM webhook URL**, + - Enter the **secret token** if your Squash TM system administrator configured it earlier. diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index d465b4e50f0..d20b19a3aaa 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The Unify Circuit integration sends notifications from GitLab to a Circuit conversation. -## Set up Unify Circuit service +## Set up Unify Circuit In Unify Circuit, [add a webhook](https://www.circuit.com/unifyportalfaqdetail?articleId=164448) and copy its URL. diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 233209966aa..c755c7a5c17 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 53177004888..fda778aa167 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -271,6 +271,7 @@ Payload example: "human_time_estimate": null, "human_time_change": null, "weight": null, + "health_status": "at_risk", "iid": 23, "url": "http://example.com/diaspora/issues/23", "state": "opened", @@ -861,6 +862,7 @@ Payload example: "visibility_level":20, "path_with_namespace":"gitlabhq/gitlab-test", "default_branch":"master", + "ci_config_path":"", "homepage":"http://example.com/gitlabhq/gitlab-test", "url":"http://example.com/gitlabhq/gitlab-test.git", "ssh_url":"git@example.com:gitlabhq/gitlab-test.git", @@ -885,7 +887,10 @@ Payload example: "title": "MS-Viewport", "created_at": "2013-12-03T17:23:34Z", "updated_at": "2013-12-03T17:23:34Z", + "last_edited_at": "2013-12-03T17:23:34Z", + "last_edited_by_id": 1, "milestone_id": null, + "state_id": 1, "state": "opened", "blocking_discussions_resolved": true, "work_in_progress": false, @@ -893,6 +898,11 @@ Payload example: "merge_status": "unchecked", "target_project_id": 14, "description": "", + "total_time_spent": 1800, + "time_change": 30, + "human_total_time_spent": "30m", + "human_time_change": "30s", + "human_time_estimate": "30m", "url": "http://example.com/diaspora/merge_requests/1", "source": { "name":"Awesome Project", @@ -929,6 +939,7 @@ Payload example: "last_commit": { "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", "message": "fixed readme", + "title": "Update file README.md", "timestamp": "2012-01-03T23:36:29+02:00", "url": "http://example.com/awesome_space/awesome_project/commits/da1560886d4f094c3e6c9ef40349f7d38b5d27d7", "author": { @@ -997,7 +1008,15 @@ Payload example: "type": "ProjectLabel", "group_id": 41 }] - } + }, + "last_edited_at": { + "previous": null, + "current": "2023-03-15 00:00:10 UTC" + }, + "last_edited_by_id": { + "previous": null, + "current": 3278533 + }, }, "assignees": [ { @@ -1074,7 +1093,8 @@ Payload example: "message": "adding an awesome page to the wiki", "slug": "awesome", "url": "http://example.com/root/awesome-project/-/wikis/awesome", - "action": "create" + "action": "create", + "diff_url": "http://example.com/root/awesome-project/-/wikis/home/diff?version_id=78ee4a6705abfbff4f4132c6646dbaae9c8fb6ec" } } ``` @@ -1392,6 +1412,7 @@ Payload example: "build_started_at": null, "build_finished_at": null, "build_duration": null, + "build_queued_duration": 1095.588715, // duration in seconds "build_allow_failure": false, "build_failure_reason": "script_failure", "retries_count": 2, // the second retry of this job @@ -1487,6 +1508,7 @@ Payload example: "deployable_id": 796, "deployable_url": "http://10.126.0.2:3000/root/test-deployment-webhooks/-/jobs/796", "environment": "staging", + "environment_tier": "staging", "environment_slug": "staging", "environment_external_url": "https://staging.example.com", "project": { diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 3d971af5c2a..7fcb2680504 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -99,7 +99,7 @@ You can define URL variables directly using the REST API. ## Configure your webhook receiver endpoint Webhook receiver endpoints should be fast and stable. -Slow and unstable receivers can be [disabled automatically](#failing-webhooks) to ensure system reliability. Webhooks that fail can lead to retries, [which cause duplicate events](#webhook-fails-or-multiple-webhook-requests-are-triggered). +Slow and unstable receivers can be [disabled automatically](#failing-webhooks) to ensure system reliability. Webhooks that fail might lead to [duplicate events](#webhook-fails-or-multiple-webhook-requests-are-triggered). Endpoints should follow these best practices: @@ -118,24 +118,28 @@ Endpoints should follow these best practices: - Never return `500` server error status responses if the event has been handled as this can cause the webhook to be [temporarily disabled](#failing-webhooks). - Invalid HTTP responses are treated as failed requests. -### Failing webhooks +## Failing webhooks -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60837) in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 15.7. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 15.7. Feature flag `web_hooks_disable_failed` removed. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60837) for project webhooks in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) for project webhooks in GitLab 15.7. Feature flag `web_hooks_disable_failed` removed. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385902) for group webhooks in GitLab 15.10. +> - [Disabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/390157) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `auto_disabling_web_hooks`. -If a webhook fails repeatedly, it may be disabled automatically. +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 `auto_disabling_web_hooks`. +On GitLab.com, this feature is available. -Webhooks that return response codes in the `5xx` range are understood to be failing +Project or group webhooks that fail four consecutive times are automatically disabled. + +Project or group webhooks that return response codes in the `5xx` range are understood to be failing intermittently and are temporarily disabled. These webhooks are initially disabled -for 1 minute, which is extended on each retry up to a maximum of 24 hours. +for one minute, which is extended on each subsequent failure up to a maximum of 24 hours. -Webhooks that return response codes in the `4xx` range are understood to be +Project or group webhooks that return response codes in the `4xx` range are understood to be misconfigured and are permanently disabled until you manually re-enable them yourself. -See [Troubleshooting](#troubleshoot-webhooks) for more information on -disabled webhooks and how to re-enable them. +For more information about disabled webhooks, see [troubleshooting](#troubleshooting). ## Test a webhook @@ -146,7 +150,7 @@ For example, to test `push events`, your project should have at least one commit NOTE: Testing is not supported for some types of events for project and groups webhooks. -Read more in [issue 379201](https://gitlab.com/gitlab-org/gitlab/-/issues/379201). +For more information, see [issue 379201](https://gitlab.com/gitlab-org/gitlab/-/issues/379201). Prerequisites: @@ -254,7 +258,7 @@ Image URLs are not rewritten if: ## Events -For more information about supported events for Webhooks, go to [Webhook events](webhook_events.md). +For more information about supported events for webhooks, see [webhook events](webhook_events.md). ## Delivery headers @@ -270,7 +274,7 @@ Webhook requests to your endpoint include the following headers: | `X-Gitlab-Event` | Name of the webhook type. Corresponds to [event types](webhook_events.md) but in the format `"<EVENT> Hook"`. | `"Push Hook"` | | `X-Gitlab-Event-UUID` | Unique ID per webhook that is not recursive. A hook is recursive if triggered by an earlier webhook that hit the GitLab instance. Recursive webhooks have the same value for this header. | `"13792a34-cac6-4fda-95a8-c58e00a3954e"` | -## Troubleshoot webhooks +## Troubleshooting > **Recent events** for group webhooks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325642) in GitLab 15.3. @@ -288,8 +292,9 @@ To view the table: 1. Scroll down to the webhooks. 1. Each [failing webhook](#failing-webhooks) has a badge listing it as: - - **Failed to connect** if it is misconfigured, and needs manual intervention to re-enable it. - - **Fails to connect** if it is temporarily disabled and is retrying later. + - **Failed to connect** if it's misconfigured and must be manually re-enabled. + - **Fails to connect** if it's temporarily disabled and is automatically + re-enabled after the timeout limit has elapsed.  @@ -325,8 +330,7 @@ Missing intermediate certificates are common causes of verification failure. ### Webhook fails or multiple webhook requests are triggered -If you are receiving multiple webhook requests, the webhook might have timed out and -been retried. +If you're receiving multiple webhook requests, the webhook might have timed out. GitLab expects a response in [10 seconds](../../../user/gitlab_com/index.md#other-limits). On self-managed GitLab instances, you can [change the webhook timeout limit](../../../administration/instance_limits.md#webhook-timeout). diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index a020cc61533..ee5ca8eca78 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md index ca25c1214b7..19f6a3e315c 100644 --- a/doc/user/project/integrations/zentao.md +++ b/doc/user/project/integrations/zentao.md @@ -1,10 +1,10 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -<!--- start_remove The following content will be removed on remove_date: '2023-05-22' --> +<!--- start_remove The following content will be removed on remove_date: '2023-08-22' --> # ZenTao (deprecated) **(PREMIUM)** diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 234faa893eb..f5d0382ccd8 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -53,7 +53,7 @@ the issue board feature. > - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to GitLab Free in 12.1. > - Multiple issue boards per group are available in GitLab Premium. -Multiple issue boards allow for more than one issue board for a given project in GitLab Free or group in GitLab Premium and higher tiers. +Multiple issue boards allow for more than one issue board for a given project in the Free tier or group in the Premium and Ultimate tier. This is great for large projects with more than one team or when a repository hosts the code of multiple products. Using the search box at the top of the menu, you can filter the listed boards. @@ -74,7 +74,7 @@ Prerequisites: To create a new issue board: -1. Select the dropdown list with the current board name in the upper left corner of the issue boards page. +1. In the upper-left corner of the issue board page, select the dropdown list with the current board name. 1. Select **Create new board**. 1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. @@ -86,7 +86,7 @@ Prerequisites: To delete the currently active issue board: -1. Select the dropdown list with the current board name in the upper left corner of the issue boards page. +1. In the upper-left corner of the issue board page, select the dropdown list with the current board name. 1. Select **Delete board**. 1. Select **Delete** to confirm. @@ -97,9 +97,9 @@ Here are some common use cases for issue boards. For examples of using issue boards along with [epics](../group/epics/index.md), [issue health status](issues/managing_issues.md#health-status), and -[scoped labels](labels.md#scoped-labels) for various Agile frameworks, check: +[scoped labels](labels.md#scoped-labels) for various Agile frameworks, see: -- The [How to use GitLab for Agile portfolio planning and project management](https://about.gitlab.com/blog/2020/11/11/gitlab-for-agile-portfolio-planning-project-management/) blog post (November 2020) +- [How to use GitLab for Agile portfolio planning and project management](https://about.gitlab.com/blog/2020/11/11/gitlab-for-agile-portfolio-planning-project-management/) blog post (November 2020) - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Cross-project Agile work management with GitLab](https://www.youtube.com/watch?v=5J0bonGoECs) (15 min, July 2020) @@ -132,10 +132,17 @@ If you have the labels **Backend**, **Frontend**, **Staging**, and With [multiple issue boards](#multiple-issue-boards), each team can have their own board to organize their workflow individually. +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=2IaMXteKSD4">Portfolio Planning - Portfolio Management</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/2IaMXteKSD4" frameborder="0" allowfullscreen> </iframe> +</figure> + #### Scrum team With multiple issue boards, each team has one board. Now you can move issues through each -part of the process. For instance: **To Do**, **Doing**, and **Done**. +part of the process. For example: **To Do**, **Doing**, and **Done**. #### Organization of topics @@ -143,7 +150,7 @@ Create lists to order issues by topic and quickly change them between topics or such as between **UX**, **Frontend**, and **Backend**. The changes are reflected across boards, as changing lists updates the labels on each issue accordingly. -#### Advanced team handover +#### Issue board workflow between teams For example, suppose we have a UX team with an issue board that contains: @@ -160,6 +167,9 @@ When finished with something, they move the card to **Frontend**. The Frontend t Cards finished by the UX team automatically appear in the **Frontend** column when they are ready for them. +For a tutorial how to set up your boards in a similar way with [scoped labels](labels.md#scoped-labels), see +[Tutorial: Set up issue boards for team hand-off](../../tutorials/boards_for_teams/index.md). + NOTE: For a broader use case, see the blog post [What is GitLab Flow?](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/). @@ -207,7 +217,7 @@ Prerequisites: - You must have at least the Reporter role for the project. When an issue is created, the system assigns a relative order value that is greater than the maximum value -of that issue's project or root group. This means the issue will be at the bottom of any issue list that +of that issue's project or root group. This means the issue is at the bottom of any issue list that it appears in. When you visit a board, issues appear ordered in any list. You're able to change @@ -226,6 +236,18 @@ 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. +## Focus mode + +To enable or disable focus mode, in the upper-right corner, select **Toggle focus mode** (**{maximize}**). +In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board. + +## Group issue boards + +Accessible at the group navigation level, a group issue board offers the same features as a project-level board. +It can display issues from all projects that fall under the group and its descendant subgroups. + +Users on GitLab Free can use a single group issue board. + ## GitLab Enterprise features for issue boards GitLab issue boards are available on the GitLab Free tier, but some @@ -245,7 +267,7 @@ This allows you to create unique boards according to your team's need. You can define the scope of your board when creating it or by selecting the **Edit board** button. After a milestone, iteration, assignee, or weight is assigned to an issue board, you can no longer -filter through these in the search bar. In order to do that, you need to remove the desired scope +filter through these in the search bar. To do that, you need to remove the desired scope (for example, milestone, assignee, or weight) from the issue board. If you don't have editing permission in a board, you're still able to see the configuration by @@ -255,14 +277,6 @@ selecting **View scope**. Watch a [video presentation](https://youtu.be/m5UTNCSqaDk) of the configurable issue board feature. -### Focus mode - -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28597) to GitLab Free SaaS in 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212331) to GitLab Free self-managed in 13.0. - -To enable or disable focus mode, select the **Toggle focus mode** button (**{maximize}**) at the top -right. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board. - ### Sum of issue weights **(PREMIUM)** > Moved to GitLab Premium in 13.9. @@ -273,13 +287,6 @@ especially in combination with [assignee lists](#assignee-lists).  -### Group issue boards - -Accessible at the group navigation level, a group issue board offers the same features as a project-level board. -It can display issues from all projects that fall under the group and its descendant subgroups. - -Users on GitLab Free can use a single group issue board. - ### Assignee lists **(PREMIUM)** As in a regular list showing all issues with a chosen label, you can add @@ -394,11 +401,11 @@ You can also [drag issues](#move-issues-and-lists) to change their position and  -## Work In Progress limits **(PREMIUM)** +## Work in progress limits **(PREMIUM)** > Moved to GitLab Premium in 13.9. -You can set a Work In Progress (WIP) limit for each issue list on an issue board. When a limit is +You can set a work in progress (WIP) limit for each issue list on an issue board. When a limit is set, the list's header shows the number of issues in the list and the soft limit of issues. You cannot set a WIP limit on the default lists (**Open** and **Closed**). @@ -413,11 +420,11 @@ Prerequisites: - You must have at least the Reporter role for the project. -To set a WIP limit for a list: +To set a WIP limit for a list, in an issue board: -1. Navigate to a Project or Group board of which you're a member. -1. Select the settings icon in a list's header. -1. Next to **Work In Progress Limit**, select **Edit**. +1. On the top of the list you want to edit, select **List actions** (**{ellipsis_v}**) **> Edit list settings**. + The list settings sidebar opens on the right. +1. Next to **Work in progress limit**, select **Edit**. 1. Enter the maximum number of issues. 1. Press <kbd>Enter</kbd> to save. @@ -439,7 +446,6 @@ When you hover over the blocked icon (**{issue-block}**), a detailed information - [Remove an existing list](#remove-a-list). - [Remove an issue from a list](#remove-an-issue-from-a-list). - [Filter issues](#filter-issues) that appear across your issue board. -- [Create workflows](#create-workflows). - [Move issues and lists](#move-issues-and-lists). - [Multi-select issue cards](#multi-select-issue-cards). - Drag and reorder the lists. @@ -475,7 +481,7 @@ Additionally, you can also see the time tracking value. ### Create a new list -Create a new list by selecting the **Create** button in the upper right corner of the issue board. +To create a new list, in the upper-right corner of the issue board, select **Create**.  @@ -493,10 +499,10 @@ Prerequisites: To remove a list from an issue board: -1. On the top of the list you want to remove, select the **List settings** icon (**{settings}**). +1. On the top of the list you want to remove, select **List actions** (**{ellipsis_v}**). The list settings sidebar opens on the right. 1. Select **Remove list**. A confirmation dialog appears. -1. Select **OK**. +1. Select **Remove list** again. ### Add issues to a list @@ -567,44 +573,6 @@ When [filtering issues](#filter-issues) in a **group** board, keep this behavior When you edit issues individually using the right sidebar, you can additionally select the milestones and labels from the **project** that the issue is from. -### Create workflows - -By reordering your lists, you can create workflows. As lists in issue boards are -based on labels, it works out of the box with your existing issues. - -So if you've already labeled things with **Backend** and **Frontend**, the issue appears in -the lists as you create them. In addition, this means you can move something between lists by -changing a label. - -A typical workflow of using an issue board would be: - -1. You [create](labels.md#create-a-label) and [prioritize](labels.md#set-label-priority) - labels to categorize your issues. -1. You have a bunch of issues (ideally labeled). -1. You visit the issue board and start [creating lists](#create-a-new-list) to - create a workflow. -1. You move issues around in lists so that your team knows who should be working - on what issue. -1. When the work by one team is done, the issue can be dragged to the next list - so someone else can pick it up. -1. When the issue is finally resolved, the issue is moved to the **Done** list - and gets automatically closed. - -For example, you can create a list based on the label of **Frontend** and one for -**Backend**. A designer can start working on an issue by adding it to the -**Frontend** list. That way, everyone knows that this issue is now being -worked on by the designers. - -Then, when they're done, all they have to do is -drag it to the next list, **Backend**. Then, a backend developer can -eventually pick it up. When they're done, they move it to **Done**, to close the -issue. - -This process can be seen clearly when visiting an issue. With every move -to another list, the label changes and a system note is recorded. - - - ### Move issues and lists You can move issues and lists by dragging them. diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index c7187323850..d286e784e0a 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -36,7 +36,7 @@ You are only allowed to attach a single Zoom meeting to an issue. If you attempt to add a second Zoom meeting using the `/zoom` quick action, it doesn't work. You need to [remove it](#removing-an-existing-zoom-meeting-from-an-issue) first. -Users on GitLab Premium and higher can also +Users on GitLab Premium and Ultimate can also [add multiple Zoom links to incidents](../../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident). ## Removing an existing Zoom meeting from an issue diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 2b302a60d63..79278d1b3ad 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -85,18 +85,21 @@ Learn how to create [merge requests for confidential issues](../merge_requests/c There are two kinds of level access for confidential issues. The general rule is that confidential issues are visible only to members of a project with at -least the Reporter role. However, a guest user can also create +least the **Reporter role**. + +However, a user with the **Guest role** can create confidential issues, but can only view the ones that they created themselves. -Users with the Guest role or non-members can also read the confidential issue if they are assigned to the issue. + +Users with the Guest role or non-members can read the confidential issue if they are assigned to the issue. When a Guest user or non-member is unassigned from a confidential issue, they can no longer view it. -Confidential issues are also hidden in search results for unprivileged users. +Confidential issues are hidden in search results for unprivileged users. For example, here's what a user with the Maintainer role and the Guest role -sees in the project's search results respectively. +sees in the project's search results: -| Maintainer role | Guest role | -|:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------| +| Maintainer role | Guest role | +|:----------------|:-----------| |  |  | ## Related topics diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md index 5ebb2fc2e1c..4511c89b0ff 100644 --- a/doc/user/project/issues/create_issues.md +++ b/doc/user/project/issues/create_issues.md @@ -78,7 +78,7 @@ Prerequisites: To create an issue from another issue: -1. In an existing issue, select the vertical ellipsis (**{ellipsis_v}**). +1. In an existing issue, select **Issue actions** (**{ellipsis_v}**). 1. Select **New related issue**. 1. Complete the [fields](#fields-in-the-new-issue-form). The new issue form has a **Relate to issue #123** checkbox, where `123` is the ID of the @@ -100,7 +100,7 @@ To create an issue from a project issue board: 1. On the top bar, select **Main menu > Projects** and find your project. 1. Select **Issues > Boards**. -1. At the top of a board list, select **New issue** (**{plus-square}**). +1. At the top of a board list, select **List actions** (**{ellipsis_v}**) **> Create new issue**. 1. Enter the issue's title. 1. Select **Create issue**. @@ -108,7 +108,7 @@ To create an issue from a group issue board: 1. On the top bar, select **Main menu > Groups** and find your group. 1. Select **Issues > Boards**. -1. At the top of a board list, select **New issue** (**{plus-square}**). +1. At the top of a board list, select **List actions** (**{ellipsis_v}**) **> Create new issue**. 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**. @@ -118,9 +118,6 @@ example, if the list is scoped to a label `Frontend`, the new issue also has thi ## By sending an email -> - Generated email address format changed in GitLab 11.7. -> - The older format is still supported, so existing aliases and contacts still work. - You can send an email to create an issue in a project on the project's **Issues List** page. diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 52da1acd32a..f1f41de7cb4 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -39,10 +39,10 @@ git commit -m "this is my commit message. Ref projectname#xxx" ``` If they are not in the same group, you can add the full URL to the issue -(`https://gitlab.com/<username>/<projectname>/issues/<xxx>`). +(`https://gitlab.com/<username>/<projectname>/-/issues/<xxx>`). ```shell -git commit -m "this is my commit message. Related to https://gitlab.com/<username>/<projectname>/issues/<xxx>" +git commit -m "this is my commit message. Related to https://gitlab.com/<username>/<projectname>/-/issues/<xxx>" ``` Of course, you can replace `gitlab.com` with the URL of your own GitLab instance. diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 8a6683a55b5..d23650e973a 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Import +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -36,8 +36,8 @@ To import issues: 1. Go to your project's Issues list page. 1. Open the import feature, depending if the project has issues: - - Existing issues are present: Select the import icon in the upper right, next to **Edit issues**. - - Project has no issues: Select **Import CSV** in the middle of the page. + - The project has existing issues: in the upper-right corner, next to **Bulk edit**, select **Actions** (**{ellipsis_v}**) **> Import CSV**. + - The project has no issues: in the middle of the page, select **Import CSV**. 1. Select the file you want to import, and then select **Import issues**. The file is processed in the background, and a notification email is sent diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index f43f87119a6..10b29feb072 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -227,6 +227,19 @@ New discussion threads get different pin numbers, which you can use to refer to In GitLab 12.5 and later, new discussions are output to the issue activity, so that everyone involved can participate in the discussion. +## Delete a comment from a design + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385100) in GitLab 15.9. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To delete a comment from a design: + +1. On the comment you want to delete, select **More actions** **{ellipsis_v}** **> Delete comment**. +1. On the confirmation dialog box, select **Delete comment**. + ## Resolve a discussion thread on a design > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13049) in GitLab 13.1. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index f41c90a74a5..63b60e4538f 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -49,7 +49,8 @@ server's time zone. Issues with due dates can also be exported as an iCalendar feed. The URL of the feed can be added to calendar applications. The feed is accessible by selecting -the **Subscribe to calendar** button on the following pages: +the **Subscribe to calendar** option in the **Actions** (**{ellipsis_v}**) dropdown +list on the following pages: - The **Assigned Issues** page linked on the right side of the GitLab header - The **Project Issues** page diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index d852ad3262b..05c348acf58 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -1,5 +1,4 @@ --- -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/issue_weight.html' stage: Plan group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index c16074ea1d8..276cc3bc7a5 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -54,7 +54,7 @@ To edit multiple issues at the same time: 1. On the top bar, select **Main 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 **Bulk edit**. 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**. @@ -87,7 +87,7 @@ To edit multiple issues at the same time: 1. On the top bar, select **Main 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 **Bulk edit**. 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**. @@ -103,7 +103,7 @@ When bulk editing issues in a group, you can edit the following attributes: ## Move an issue 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 +The original issue is not deleted. A [system note](../system_notes.md), which indicates where it came from and went to, is added to both issues. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. @@ -136,7 +136,7 @@ To move multiple issues at the same time: 1. On the top bar, select **Main 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 **Bulk edit**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to move. 1. From the right sidebar, select **Move selected**. 1. From the dropdown list, select the destination project. @@ -209,6 +209,10 @@ 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. +<!-- Delete when the `moved_mr_sidebar` feature flag is removed --> +If you don't see this action at the top of an issue, your project or instance might have +enabled a feature flag for [moved actions](../merge_requests/index.md#move-sidebar-actions). + ### Reopen a closed issue Prerequisites: @@ -298,7 +302,7 @@ To disable automatic issue closing: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. -1. Expand **Default branch**. +1. Expand **Branch defaults**. 1. Clear the **Auto-close referenced issues on default branch** checkbox. 1. Select **Save changes**. @@ -344,7 +348,7 @@ Prerequisites: To delete an issue: -1. In an issue, select the vertical ellipsis (**{ellipsis_v}**). +1. In an issue, select **Issue actions** (**{ellipsis_v}**). 1. Select **Delete issue**. Alternatively: @@ -362,7 +366,7 @@ You can promote an issue to an [epic](../../group/epics/index.md) in the immedia To promote an issue to an epic: -1. In an issue, select the vertical ellipsis (**{ellipsis_v}**). +1. In an issue, select **Issue actions** (**{ellipsis_v}**). 1. Select **Promote to epic**. Alternatively, you can use the `/promote` [quick action](../quick_actions.md#issues-merge-requests-and-epics). @@ -400,7 +404,7 @@ To view all issues assigned to you: Or: - To use a [keyboard shortcut](../../shortcuts.md), press <kbd>Shift</kbd> + <kbd>i</kbd>. -- On the top bar, in the upper right, select **{issues}** **Issues**. +- On the top bar, in the upper-right corner, select **Issues** (**{issues}**). ## Filter the list of issues @@ -472,6 +476,10 @@ 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). +<!-- Delete when the `moved_mr_sidebar` feature flag is removed --> +If you don't see this action on the right sidebar, your project or instance might have +enabled a feature flag for [moved actions](../merge_requests/index.md#move-sidebar-actions). + ## Copy issue email address > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18816) in GitLab 13.8. diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index a2f90d5c444..829e44eae9a 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -73,7 +73,7 @@ then issues with a milestone without a due date. ## Sorting by popularity When you sort by **Popularity**, the issue order changes to sort descending by the -number of upvotes ([awarded](../../award_emojis.md) a "thumbs up" emoji) +number of upvotes ([emoji reactions](../../award_emojis.md) with the "thumbs up") on each issue. You can use this to identify issues that are in high demand. ## Sorting by priority diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index f9e3f1b9225..2af15e06b98 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -136,7 +136,7 @@ To do so: 1. Fill in the name field. You can't specify a description if creating a label this way. You can add a description later by [editing the label](#edit-a-label). 1. Select a color by selecting from the available colors, or enter a hex color value for a specific color. -1. Select **Create**. +1. Select **Create**. Your label is created and selected. ### Create a group label @@ -381,7 +381,7 @@ issue is now under review, they assign the `workflow::review`, and the `workflow is removed. The same happens when you move issues across label lists in an -[issue board](issue_board.md#create-workflows). With scoped labels, team members not working in an +[issue board](issue_board.md). With scoped labels, team members not working in an issue board can also advance workflow states consistently in issues themselves. For a video explanation, see: diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index c7d45b0bd15..6e20492db05 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Organization +stage: Data Stores +group: Tenant Scale info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 4dda68a6d08..452363c3d9a 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Organization +stage: Data Stores +group: Tenant Scale info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -28,17 +28,21 @@ To invite a group to a project, you must be at least one of the following: In addition: -- The group you're inviting must have a more restrictive - [visibility level](../../public_access.md#project-and-group-visibility) - than the project. For example, you can invite: - - A private group to a public project. - - An internal group to a public project. - - A private group to an internal project. +- You must be a member of the group or the subgroup being invited. -- The group or subgroup must be in the project's [namespace](../../namespace/index.md). +- The [visibility level](../../public_access.md#project-and-group-visibility) of the group you're inviting +must be at least as restrictive as that of the project. For example, you can invite: + - A _private_ group to a _private_ project + - A _private_ group to an _internal_ project. + - A _private_ group to a _public_ project. + - An _internal_ group to an _internal_ project. + - An _internal_ group to a _public_ project. + - A _public_ group to a _public_ project. + +- If the project's root ancestor group [does not allow the project to be shared outside the hierarchy](../../group/access_and_permissions.md#prevent-group-sharing-outside-the-group-hierarchy), the invited group or subgroup must be in the project's [namespace](../../namespace/index.md). For example, a project in the namespace `group/subgroup01/project`: - Can be shared with `group/subgroup02` or `group/subgroup01/subgroup03`. - - Cannot be shared with `group`. + - Cannot be shared with `group_abc`. ## Share a project with a group @@ -70,17 +74,21 @@ are given access to the project. In addition: ## Maximum role +When you invite a group to a project, the maximum role is the highest level of access the invited group members are allowed to have in the project. + When multiple groups contain the same members, and the groups have access to the same project, the group members are -given the most restrictive role for the project. - -This most restrictive role is called the *maximum role*, or **Max role**. +given the highest access level of the two for the project. The member's **Max role** is the more restrictive of: - The role the user is assigned for the group. - The role you chose when you invited the group to the project. +NOTE: +The Max role does not elevate the privileges of users. +For example, if a group member has the role of Developer, and the group is invited to a project with a Max role of Maintainer, the member's role is not elevated to Maintainer. + ### View the member's Max role To view the maximum role assigned to a member: diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 0729e024df4..d5851050fd4 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -61,14 +61,14 @@ In the following example: To change or add a commit to the contributor's merge request: 1. Go to the merge request. -1. In the upper right corner, select **Code**, then select **Check out branch**. +1. In the upper-right corner, select **Code**, then select **Check out branch**. 1. In the modal window, select **Copy** (**{copy-to-clipboard}**). 1. In your terminal, go to your cloned version of the repository, and paste the commands. For example: ```shell git fetch "git@gitlab.com:contributor/forked-project.git" 'fork-branch' - git checkout -b contributor/fork-branch' FETCH_HEAD + git checkout -b 'contributor/fork-branch' FETCH_HEAD ``` Those commands fetch the branch from the forked project, and create a local branch diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 21e2055cb61..717358df9f3 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -3,7 +3,6 @@ stage: Create group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference, concepts -disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/approvals/index.html' --- # Merge request approvals **(FREE)** @@ -17,7 +16,7 @@ approve merge requests, these approvals are [optional](#optional-approvals). flexibility: - Create required [rules](rules.md) about the number and type of approvers before work can merge. -- Specify a list of users who act as [code owners](../../code_owners.md) for specific files, +- Specify a list of users who act as [code owners](../../codeowners/index.md) for specific files, and require their approval before work can merge. You can configure merge request approvals on a per-project basis, and some approvals can be configured @@ -36,7 +35,7 @@ required approvals before work can merge into your project. You can also extend rules to define what types of users can approve work. Some examples of rules you can create include: - Users with specific permissions can always approve work. -- [Code owners](../../code_owners.md) can approve work for files they own. +- [Code owners](../../codeowners/index.md) can approve work for files they own. - Users with specific permissions can approve work, [even if they don't have merge rights](rules.md#merge-request-approval-segregation-of-duties) to the repository. @@ -102,20 +101,31 @@ Without the approvals, the work cannot merge. Required approvals enable multiple database, for all proposed code changes. - Use the [code owners of changed files](rules.md#code-owners-as-eligible-approvers), to determine who should review the work. -- Require an [approval before merging code that causes test coverage to decline](../../../../ci/pipelines/settings.md#coverage-check-approval-rule) +- Require an [approval before merging code that causes test coverage to decline](../../../../ci/testing/code_coverage.md#coverage-check-approval-rule). - Users on GitLab Ultimate can also [require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) before merging code that could introduce a vulnerability. ## Invalid rules -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334698) in GitLab 15.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334698) in GitLab 15.1. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/389905) in GitLab 15.11 [with a flag](../../../../administration/feature_flags.md) named `invalid_scan_result_policy_prevents_merge`. Disabled by default. -Whenever an approval rule cannot be satisfied, the rule will be displayed as `Invalid`. This applies to the following conditions: +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, +ask an administrator to [enable the feature flag](../../../../administration/feature_flags.md) named `invalid_scan_result_policy_prevents_merge`. +On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. + +Whenever an approval rule cannot be satisfied, the rule is displayed as **(!) Auto approved**. This applies to the following conditions: - The only eligible approver is the author of the merge request. - No eligible approvers (either groups or users) have been assigned to the approval rule. +- The number of required approvals is more than the number of eligible approvers. + +These rules are automatically approved to unblock their respective merge requests, +unless they were created through a security policy. -These rules will be automatically approved to unblock their respective merge requests. +Invalid approval rules created through a security policy are presented with **(!) Action Required** +and are not automatically approved, blocking their respective merge requests. ## Related topics diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 0a5e7c29860..d55ca5dff04 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -53,7 +53,7 @@ To add a merge request approval rule: 1. Select **Add approval rule**. -Users of GitLab Premium and higher tiers can create [additional approval rules](#add-multiple-approval-rules). +Users of GitLab Premium and Ultimate tiers can create [additional approval rules](#add-multiple-approval-rules). Your configuration for approval rule overrides determines if the new rule is applied to existing merge requests: @@ -91,7 +91,7 @@ To edit a merge request approval rule: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab 11.10. -In GitLab Premium and higher tiers, you can enforce multiple approval rules on a +In GitLab Premium and Ultimate tiers, you can enforce multiple approval rules on a merge request, and multiple default approval rules for a project. If your tier supports multiple default rules: @@ -106,6 +106,9 @@ reduces the number of approvals left (the **Approvals** column) for all rules th  +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Multiple Approvers](https://www.youtube.com/watch?v=8JQJ5821FrA). + ## Eligible approvers > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. @@ -131,7 +134,7 @@ who commented on the merge request. It helps authors and reviewers identify who contact with questions about the merge request's content. If the number of required approvals is greater than the number of assigned approvers, -approvals from other users with Developer [permissions](../../../permissions.md) or higher +approvals from other users with at least the Developer [role](../../../permissions.md) in the project counts toward meeting the required number of approvals, even if the users were not explicitly listed in the approval rules. @@ -158,7 +161,7 @@ approve in these ways: > Moved to GitLab Premium in 13.9. -If you add [code owners](../../code_owners.md) to your repository, the owners of files +If you add [code owners](../../codeowners/index.md) to your repository, the owners of files become eligible approvers in the project. To enable this merge request approval rule: 1. Go to your project and select **Settings > Merge requests**. @@ -241,6 +244,28 @@ approval rule for certain branches: 1. To enable this configuration, read [Code Owner's approvals for protected branches](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch). +## Code coverage check approval + +You can require specific approvals in the case that a merge request would reduce code test +coverage. + +For more information, see [Coverage check approval rule](../../../../ci/testing/code_coverage.md#coverage-check-approval-rule). + +## Security Approvals **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. + +You can use [scan result policies](../../../application_security/policies/scan-result-policies.md#scan-result-policy-editor) to define security approvals based on the status of vulnerabilities in the merge request and the default branch. +Details for each security policy is shown in the Security Approvals section of your Merge Request configuration. + +The security approval rules are applied to all merge requests until the pipeline is complete. The application of the +security approval rules prevents users from merging in code before the security scans run. After the pipeline is +complete, the security approval rules are checked to determine if the security approvals are still required. + + + +These policies are both created and edited in the [security policy editor](../../../application_security/policies/index.md#policy-editor). + ## Troubleshooting ### Approval rule name can't be blank @@ -262,18 +287,3 @@ isn't recognized as a valid Code Owner for the project, nor does it display in t project's **Approvals** list. To fix this problem, add the approval group as a shared group high enough in the shared hierarchy so the project requiring review inherits this group of users. - -## Security Approvals **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. - -You can use [scan result policies](../../../application_security/policies/scan-result-policies.md#scan-result-policy-editor) to define security approvals based on the status of vulnerabilities in the merge request and the default branch. -Details for each security policy is shown in the Security Approvals section of your Merge Request configuration. - -The security approval rules are applied to all merge requests until the pipeline is complete. The application of the -security approval rules prevents users from merging in code before the security scans run. Once the pipeline is -complete, the security approval rules are checked to determine if the security approvals are still required. - - - -These policies are both created and edited in the [security policy editor](../../../application_security/policies/index.md#policy-editor). diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 1ab564c108b..6c079dc9319 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -78,13 +78,13 @@ their own. To do this: it can't be changed at the project level. 1. Select **Save changes**. -Depending on your version of GitLab, [code owners](../../code_owners.md) who commit +Depending on your version of GitLab, [code owners](../../codeowners/index.md) who commit to a merge request may or may not be able to approve the work: -- In GitLab 13.10 and earlier, [code owners](../../code_owners.md) who commit +- In GitLab 13.10 and earlier, code owners who commit to a merge request can approve it, even if the merge request affects files they own. - In [GitLab 13.11 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/331548), - [code owners](../../code_owners.md) who commit + code owners who commit to a merge request cannot approve it, when the merge request affects files they own. For more information, see the [official Git documentation](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History). @@ -121,7 +121,7 @@ permission enables an electronic signature for approvals, such as the one define ## Remove all approvals when commits are added to the source branch By default, an approval on a merge request is removed when you add more changes -after the approval. In GitLab Premium and higher tiers, to keep existing approvals +after the approval. In GitLab Premium and Ultimate tiers, to keep existing approvals after more changes are added to the merge request: 1. On the left sidebar, select **Settings > Merge requests**. @@ -140,7 +140,7 @@ However, approvals are reset if the target branch is changed. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90578) in GitLab 15.3. -If you only want to remove approvals by Code Owners whose files have been changed: +If you only want to remove approvals by Code Owners whose files have been changed when a commit is added: Prerequisite: @@ -153,13 +153,6 @@ To do this: select **Remove approvals by Code Owners if their files changed**. 1. Select **Save changes**. -## Code coverage check approvals - -You can require specific approvals if a merge request would result in a decline in code test -coverage. - -For more information, see [Coverage check approval rule](../../../../ci/pipelines/settings.md#coverage-check-approval-rule). - ## Settings cascading > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.4. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../../../administration/feature_flags.md), disabled by default. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 9fac872ac4b..004d24778b7 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -55,7 +55,7 @@ by the merge request: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**, and find your merge request. 1. Scroll to the merge request reports section, and find the **Merged by** report. -1. In the upper right, select **Cherry-pick**: +1. In the upper-right corner, select **Cherry-pick**:  1. In the modal window, select the project and branch to cherry-pick into. @@ -72,7 +72,8 @@ To cherry-pick a commit from the list of all commits for a project: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Commits**. -1. Select the title of the commit you want to cherry-pick. +1. Select the [title](https://git-scm.com/docs/git-commit#_discussion) of the commit you want to cherry-pick. +1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In the modal window, select the project and branch to cherry-pick into. 1. Optional. Select **Start a new merge request with these changes**. 1. Select **Cherry-pick**. @@ -86,7 +87,7 @@ list of commits included in a merge request: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**, and find your merge request. 1. In the merge request's secondary menu, select **Commits** to display the commit details page. -1. Select the title of the commit you want to cherry-pick. +1. Select the [title](https://git-scm.com/docs/git-commit#_discussion) of the commit you want to cherry-pick. 1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In the modal window, select the project and branch to cherry-pick into. 1. Optional. Select **Start a new merge request with these changes**. @@ -100,7 +101,8 @@ when you view that file in your project's Git repository: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Files** and go to the file changed by the commit. -1. Select **History**, then select the title of the commit you want to cherry-pick. +1. Select **History**, then select the [title](https://git-scm.com/docs/git-commit#_discussion) + of the commit you want to cherry-pick. 1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In the modal window, select the project and branch to cherry-pick into. 1. Optional. Select **Start a new merge request with these changes**. @@ -123,7 +125,7 @@ project, from the GitLab user interface: ## View system notes for cherry-picked commits -When you cherry-pick a merge commit in the GitLab UI or API, GitLab adds a system note +When you cherry-pick a merge commit in the GitLab UI or API, GitLab adds a [system note](../system_notes.md) to the related merge request thread in the format **{cherry-pick-commit}** `[USER]` **picked the changes into the branch** `[BRANCHNAME]` with commit** `[SHA]` `[DATE]`: diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index a9f67c39ae8..cc6ecd8398f 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -1,11 +1,59 @@ --- -redirect_to: '../merge_requests/index.md' -remove_date: '2023-03-12' +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/product/ux/technical-writing/#assignments +type: index, reference --- -This document was removed. +# Merge request commits **(FREE)** -<!-- This redirect file can be deleted after <2023-03-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> +Each merge request has a history of the commits made to the source branch +after the merge request was created. + +These commits are displayed on the merge request's **Commits** tab. +From this tab, you can review commit messages and copy a commit's SHA when you need to +[cherry-pick changes](cherry_pick_changes.md). + +## Navigate merge request commits + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. + +To navigate commits in a merge request: + +1. Select the **Commits** tab. +1. Select the commit link. The most recent commit is displayed. +1. Navigate through the commits by either: + + - Selecting **Prev** and **Next** buttons below the tab buttons. + - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. + + + +## View merge request commits in context + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29274) in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `context_commits`. Enabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) in GitLab 14.8. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) in GitLab 14.9. [Feature flag `context_commits`](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) removed. + +When reviewing a merge request, it helps to have more context about the changes +made. That includes unchanged lines in unchanged files, and previous commits +that have already merged that the change is built on. + +To add previously merged commits to a merge request for more context: + +1. Go to your merge request. +1. Select the **Commits** tab. +1. Scroll to the end of the list of commits, and select **Add previously merged commits**: +1. Select the commits that you want to add. +1. Select **Save changes**. + +## View diffs between commits + +To view the changes between previously merged commits: + +1. On your merge request, select the **Changes** tab. +1. By **Compare**, select the commit you want to view: + +  + +If you selected to add previously merged commits, they are displayed in the list. diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md index 307998f697d..edcc5711b98 100644 --- a/doc/user/project/merge_requests/confidential.md +++ b/doc/user/project/merge_requests/confidential.md @@ -65,7 +65,7 @@ Your branch, merge requests, and commits remain in your private fork. This preve prematurely revealing confidential information. Open a merge request -[from your fork to the upstream repository](../repository/forking_workflow.md#merging-upstream) when: +[from your fork to the upstream repository](../repository/forking_workflow.md#merge-changes-back-upstream) when: - You are satisfied the problem is resolved in your private fork. - You are ready to make the confidential commits public. diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md index 932eec5e631..cc8f8cb2fe6 100644 --- a/doc/user/project/merge_requests/conflicts.md +++ b/doc/user/project/merge_requests/conflicts.md @@ -162,9 +162,8 @@ merge commit. Verify it contains no unintended changes and doesn't break your bu ## Related topics -- [Introduction to Git rebase and force-push](../../../topics/git/git_rebase.md). -- [Git GUI apps](https://git-scm.com/downloads/guis) to help you visualize the - differences between branches and resolve them. +- [Introduction to Git rebase and force-push](../../../topics/git/git_rebase.md) +- [Git applications for visualizing the Git workflow](https://git-scm.com/downloads/guis) <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 875312bbb7c..a91d324016a 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -3,15 +3,17 @@ 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/product/ux/technical-writing/#assignments description: "How to create merge requests in GitLab." -disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' --- # Creating merge requests **(FREE)** -There are many different ways to create a merge request. +GitLab provides many different ways to create a merge request. NOTE: -Use [branch naming patterns](../repository/branches/index.md#naming) to streamline merge request creation. +GitLab enforces [branch naming rules](../repository/branches/index.md#name-your-branch) +to prevent problems, and provides +[branch naming patterns](../repository/branches/index.md#prefix-branch-names-with-issue-numbers) +to streamline merge request creation. ## From the merge request list @@ -19,7 +21,7 @@ You can create a merge request from the list of merge requests. 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Merge requests**. -1. In the upper right, select **New merge request**. +1. In the upper-right corner, select **New merge request**. 1. Select a source and target branch and then **Compare branches and continue**. 1. Fill out the fields and select **Create merge request**. @@ -34,7 +36,8 @@ be associated with a given target branch at a time. If your development workflow requires an issue for every merge request, you can create a branch directly from the issue to speed the process up. The new branch, and later its merge request, are marked as related to this issue. -After merging the merge request, the issue is closed automatically, unless [automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing). +After merging the merge request, the issue is closed automatically, unless +[automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing). You can see a **Create merge request** dropdown list below the issue description. NOTE: @@ -50,7 +53,7 @@ instead of immediately creating the merge request. - Your project is private and the issue is confidential. To make this button appear, one possible workaround is to -[remove your project's fork relationship](../settings/index.md#remove-a-fork-relationship). +[remove your project's fork relationship](../repository/forking_workflow.md#unlink-a-fork). After removal, the fork relationship cannot be restored. This project can no longer be able to receive or send merge requests to the source project, or other forks. @@ -58,8 +61,8 @@ The dropdown list contains the options **Create merge request and branch** and * After selecting one of these options, a new branch or branch and merge request is created based on your project's [default branch](../repository/branches/default.md). -The branch name is based on your project's branch name template. The default template -is `%{id}-%{title}`. Supported variables for branch name templates are `%{id}` and `%{title}`. +The branch name is based on your project's [branch name template](../repository/branches/index.md), +but this value can be changed. When you select **Create branch** in an empty repository project, GitLab performs these actions: @@ -83,7 +86,7 @@ You can create a merge request when you add, edit, or upload a file to a reposit 1. [Add, edit, or upload](../repository/web_editor.md) a file to the repository. 1. In the **Commit message**, enter a reason for the commit. -1. Select the **Target branch** or create a new branch by typing the name (without spaces, capital letters, or special chars). +1. Select the **Target branch** or create a new branch by typing the name (without spaces). 1. Select the **Start a new merge request with these changes** checkbox or toggle. This checkbox or toggle is visible only if the target is not the same as the source branch, or if the source branch is protected. 1. Select **Commit changes**. @@ -151,9 +154,8 @@ You can create a merge request from your fork to contribute back to the main pro 1. Select **Create merge request**. After your work is merged, if you don't intend to -make any other contributions to the upstream project, you can unlink your -fork from its upstream project. Go to **Settings > Advanced Settings** and -[remove the forking relationship](../settings/index.md#remove-a-fork-relationship). +make any other contributions to the upstream project, you can +[unlink your fork](../repository/forking_workflow.md#unlink-a-fork) from its upstream project. For more information, [see the forking workflow documentation](../repository/forking_workflow.md). @@ -171,7 +173,7 @@ To create a merge request by sending an email: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Merge requests**. -1. In the upper right, select **Email a new merge request to this project**. +1. In the upper-right corner, select **Email a new merge request to this project**. An email address is displayed. Copy this address. Ensure you keep this address private. 1. Open an email and compose a message with the following information: diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 9028a9411ea..f40b82a6280 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -16,7 +16,7 @@ To export merge requests to a CSV file: 1. On the left sidebar, select **Merge requests** . 1. Add any searches or filters. This can help you keep the size of the CSV file under the 15 MB limit. The limit ensures the file can be emailed to a variety of email providers. -1. Select **Export as CSV** (**{export}**). +1. Select **Actions** (**{ellipsis_v}**) **> Export as CSV**. 1. Confirm the correct number of merge requests are to be exported. 1. Select **Export merge requests**. diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md index 231c1dda5b7..3d92fc9a91e 100644 --- a/doc/user/project/merge_requests/dependencies.md +++ b/doc/user/project/merge_requests/dependencies.md @@ -85,7 +85,7 @@ other specific work merges, even if the merge request is in a different project. Prerequisites: - You must have at least the Developer role or be allowed to create merge requests in the project. -- The dependent merge request must be in a project in a **PREMIUM** or higher tier. +- The dependent merge request must be in a project in the Premium or Ultimate tier. To create a new merge request and mark it as dependent on another: diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index 62820988701..88e5e4a6283 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -3,7 +3,6 @@ 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/product/ux/technical-writing/#assignments type: reference, concepts -disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/work_in_progress_merge_requests.html' --- # Draft merge requests **(FREE)** @@ -31,7 +30,7 @@ There are several ways to flag a merge request as a draft: below the **Title** field. - **Commenting in an existing merge request**: Add the `/draft` [quick action](../quick_actions.md#issues-merge-requests-and-epics) - in a comment. GitLab 15.4 [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) the toggle behavior of `/draft`. To mark a merge request as ready, use `/ready`. + in a comment. To mark a merge request as ready, use `/ready`. - **Creating a commit**: Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the beginning of a commit message targeting the merge request's source branch. This is not a toggle, and adding this text again in a later commit doesn't mark the diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md deleted file mode 100644 index 4125d8e8fdb..00000000000 --- a/doc/user/project/merge_requests/getting_started.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2023-03-31' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after <2023-03-31>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/merge_requests/img/commit_nav_v16_0.png b/doc/user/project/merge_requests/img/commit_nav_v16_0.png Binary files differnew file mode 100644 index 00000000000..6005e516fff --- /dev/null +++ b/doc/user/project/merge_requests/img/commit_nav_v16_0.png diff --git a/doc/user/project/merge_requests/img/previously_merged_commits_v16_0.png b/doc/user/project/merge_requests/img/previously_merged_commits_v16_0.png Binary files differnew file mode 100644 index 00000000000..31204b6e801 --- /dev/null +++ b/doc/user/project/merge_requests/img/previously_merged_commits_v16_0.png diff --git a/doc/user/project/merge_requests/img/remove_source_branch_status.png b/doc/user/project/merge_requests/img/remove_source_branch_status.png Binary files differdeleted file mode 100644 index afd93207e02..00000000000 --- a/doc/user/project/merge_requests/img/remove_source_branch_status.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index a633366cc62..a65c5518658 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -26,11 +26,27 @@ view [this GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE). Learn the various ways to [create a merge request](creating_merge_requests.md). +### Use merge request templates + +When you create a merge request, GitLab checks for the existence of a +[description template](../description_templates.md) to add data to your merge request. +GitLab checks these locations in order from 1 to 5, and applies the first template +found to your merge request: + +| Name | Project UI<br>setting | Group<br>`default.md` | Instance<br>`default.md` | Project<br>`default.md` | No template | +| :-- | :--: | :--: | :--: | :--: | :--: | +| Standard commit message | 1 | 2 | 3 | 4 | 5 | +| Commit message with an [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) like `Closes #1234` | 1 | 2 | 3 | 4 | 5 \* | +| Branch name [prefixed with an issue ID](../repository/branches/index.md#prefix-branch-names-with-issue-numbers), like `1234-example` | 1 \* | 2 \* | 3 \* | 4 \* | 5 \* | + +NOTE: +Items marked with an asterisk (\*) also append an [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically). + ## View merge requests You can view merge requests for your project, group, or yourself. -### View merge requests for a project +### For a project To view all merge requests for a project: @@ -39,7 +55,7 @@ To view all merge requests for a project: Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd>m</kbd>. -### View merge requests for all projects in a group +### For all projects in a group To view merge requests for all projects in a group: @@ -48,7 +64,7 @@ To view merge requests for all projects in a group: If your group contains subgroups, this view also displays merge requests from the subgroup projects. -### View all merge requests assigned to you +### Assigned to you To view all merge requests assigned to you: @@ -65,7 +81,7 @@ or: or: -1. On the top bar, in the upper right, select **{merge-request-open}** **Merge requests**. +1. On the top bar, in the upper-right corner, select **Merge requests** (**{merge-request-open}**). 1. From the dropdown list, select **Assigned to you**. ## Filter the list of merge requests @@ -79,12 +95,12 @@ To filter the list of merge requests: 1. Above the list of merge requests, select **Search or filter results...**. 1. From the dropdown list, select the attribute you wish to filter by. Some examples: - - [**By environment or deployment date**](#filter-merge-requests-by-environment-or-deployment-date). + - [**By environment or deployment date**](#by-environment-or-deployment-date). - **ID**: Enter filter `#30` to return only merge request 30. - User filters: Type (or select from the dropdown list) any of these filters to display a list of users: - **Approved-By**, for merge requests already approved by a user. **(PREMIUM)**. - **Approver**, for merge requests that this user is eligible to approve. - (For more information, read about [Code owners](../code_owners.md)). **(PREMIUM)** + (For more information, read about [Code owners](../codeowners/index.md)). **(PREMIUM)** - **Reviewer**, for merge requests reviewed by this user. 1. Select or type the operator to use for filtering the attribute. The following operators are available: @@ -100,7 +116,7 @@ To filter the list of merge requests: GitLab displays the results on-screen, but you can also [retrieve them as an RSS feed](../../search/index.md#retrieve-search-results-as-feed). -### Filter merge requests by environment or deployment date +### By environment or deployment date > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44041) in GitLab 13.6. @@ -251,14 +267,15 @@ after merging does not retarget open merge requests. This improvement is <!-- When the `moved_mr_sidebar` feature flag is removed, delete this topic and update the steps for these actions like in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87727/diffs?diff_id=522279685#5d9afba799c4af9920dab533571d7abb8b9e9163 --> -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85584) in GitLab 14.10 [with a flag](../../../administration/feature_flags.md) named `moved_mr_sidebar`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85584) in GitLab 14.10 [with a flag](../../../administration/feature_flags.md) named `moved_mr_sidebar`. Disabled by default. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/373757) to also move actions on issues, incidents, and epics in GitLab 16.0. FLAG: On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `moved_mr_sidebar`. On GitLab.com, this feature is enabled in the following projects: `gitlab-org/gitlab`, `gitlab-com/www-gitlab-com`, and `gitlab-org/customers-gitlab-com`. -When this feature flag is enabled, you can find the following actions in -**Merge request actions** (**{ellipsis_v}**) in the upper right: +When this feature flag is enabled, in the upper-right corner, +**Merge request actions** (**{ellipsis_v}**) contains the following actions: - The [notifications](../../profile/notifications.md#edit-notification-settings-for-issues-merge-requests-and-epics) toggle - Mark merge request as ready or [draft](../merge_requests/drafts.md) @@ -266,6 +283,8 @@ When this feature flag is enabled, you can find the following actions in - [Lock discussion](../../discussions/index.md#prevent-comments-by-locking-the-discussion) - Copy reference +In GitLab 16.0 and later, similar action menus are available on issues, incidents, and epics. + When this feature flag is disabled, these actions are in the right sidebar. ## Merge request workflows @@ -295,6 +314,43 @@ For a web developer writing a webpage for your company's website: 1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). 1. Your production team [cherry-picks](cherry_pick_changes.md) the merge commit into production. +## Filter activity in a merge request + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115383) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `mr_activity_filters`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. +To make it available per user, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `mr_activity_filters` for individual or groups of users. +On GitLab.com, this feature unavailable. + +To understand the history of a merge request, filter its activity feed to show you +only the items that are relevant to you. + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests**. +1. Select a merge request. +1. Scroll to **Activity**. +1. On the right side of the page, select **Activity filter** to show the filter options. + If you've selected filter options previously, this field shows a summary of your + choices, like **Activity + 5 more**. +1. Select the types of activity you want to see. Options include: + + - Assignees & Reviewers + - Approvals + - Comments + - Commits & branches + - Edits + - Labels + - Lock status + - Mentions + - Merge request status + - Tracking + +1. Optional. Select **Sort** (**{sort-lowest}**) to reverse the sort order. + +Your selection persists across all merge requests. You can also change the +sort order by clicking the sort button on the right. + ## Related topics - [Create a merge request](creating_merge_requests.md) @@ -304,7 +360,6 @@ For a web developer writing a webpage for your company's website: - [GitLab keyboard shortcuts](../../shortcuts.md) - [Comments and threads](../../discussions/index.md) - [Suggest code changes](reviews/suggestions.md) -- [Commits](commits.md) - [CI/CD pipelines](../../../ci/index.md) - [Push options](../push_options.md) for merge requests diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index f0359446b06..7588af70bd4 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -5,7 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge when pipeline succeeds **(FREE)** +# Auto-merge **(FREE)** + +> **Merge when pipeline succeeds** and **Add to merge train when pipeline succeeds** [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409530) to **Auto-merge** in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `auto_merge_labels_mr_widget`. Enabled by default. + +NOTE: +[In GitLab 16.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/359057), **Merge when pipeline succeeds** and **Add to merge train when pipeline succeeds** become **Set to auto-merge**. If you review a merge request and it's ready to merge, but the pipeline hasn't completed yet, you can set it to merge when the pipeline succeeds (MWPS). You don't @@ -147,3 +152,11 @@ merge-request-pipeline-job: Instead, use branch (`push`) pipelines or merge request pipelines, when possible. For details on avoiding two pipelines for a single merge request, read the [`rules` documentation](../../../ci/jobs/job_control.md#avoid-duplicate-pipelines). + +### Merged results pipeline allows merge, despite a failed branch pipeline + +When [the **Pipelines must succeed** setting](#require-a-successful-pipeline-for-merge) +is combined with +[the **Merged results pipelines** feature](../../../ci/pipelines/merged_results_pipelines.md), +failed branch pipeline may be ignored. +[Issue 385841](https://gitlab.com/gitlab-org/gitlab/-/issues/385841) is open to track this. diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index 1f7e15ee982..02bd4ed0502 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -228,5 +228,4 @@ workflow that requires frequent rebases. ## Related topics -- [Commits history](../commits.md) - [Squash and merge](../squash_and_merge.md) diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 5878873f209..77fd78ee0d0 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -58,7 +58,8 @@ To do this: 1. On the top bar, select **Main menu > Projects** and find your project. 1. If you know the merge request that contains the commit: 1. On the left sidebar, select **Merge requests** and identify your merge request. - 1. Select **Commits**, then select the title of the commit you want to revert. GitLab displays the contents of the commit. + 1. Select **Commits**, then select the title of the commit you want to revert. This displays the commit in the **Changes** tab of your merge request. + 1. Select the commit hash you want to revert. GitLab displays the contents of the commit. 1. If you don't know the merge request the commit originated from: 1. On the left sidebar, select **Repository > Commits**. 1. Select the title of the commit to display full information about the commit. diff --git a/doc/user/project/merge_requests/reviews/data_usage.md b/doc/user/project/merge_requests/reviews/data_usage.md index dd07f0b4a6e..f0eb3c015b6 100644 --- a/doc/user/project/merge_requests/reviews/data_usage.md +++ b/doc/user/project/merge_requests/reviews/data_usage.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Suggested Reviewers Data Usage +# Suggested Reviewers Data Usage **(ULTIMATE SAAS)** ## How it works diff --git a/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg Binary files differdeleted file mode 100644 index e8aa4b7c730..00000000000 --- a/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg Binary files differdeleted file mode 100644 index d15f5d53e55..00000000000 --- a/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg Binary files differdeleted file mode 100644 index 3e1e9c20af9..00000000000 --- a/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png b/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png Binary files differdeleted file mode 100644 index e27fa629672..00000000000 --- a/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png b/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png Binary files differdeleted file mode 100644 index 170c04542dd..00000000000 --- a/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png b/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png Binary files differdeleted file mode 100644 index 92d5ba5ddda..00000000000 --- a/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png Binary files differdeleted file mode 100644 index 80424d1f056..00000000000 --- a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg Binary files differdeleted file mode 100644 index fa8331effdb..00000000000 --- a/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png b/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png Binary files differdeleted file mode 100644 index 58e0508d8cf..00000000000 --- a/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v14_7.png b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v14_7.png Binary files differdeleted file mode 100644 index 2805ef19f2d..00000000000 --- a/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v14_7.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 5291a845437..0de38874304 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Review a merge request **(FREE)** +# Merge request reviews **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245190) in GitLab 13.9. @@ -21,16 +21,19 @@ You can review merge requests from the GitLab interface. If you install the [GitLab Workflow VS Code extension](../../repository/vscode.md), you can also review merge requests in Visual Studio Code. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Merge request review](https://www.youtube.com/watch?v=2MayfXKpU08&list=PLFGfElNsQthYDx0A_FaNNfUm9NHsK6zED&index=183). + ## Suggested reviewers **(ULTIMATE SAAS)** -> [Introduced](https://gitlab.com/groups/gitlab-org/modelops/applied-ml/review-recommender/-/epics/3) in GitLab 15.4. +> - [Introduced](https://gitlab.com/groups/gitlab-org/modelops/applied-ml/review-recommender/-/epics/3) in GitLab 15.4 as a [Beta](../../../../policy/alpha-beta-support.md#beta) feature [with a flag](../../../../administration/feature_flags.md) named `suggested_reviewers_control`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/368356) in GitLab 15.6. +> - Beta designation [removed from the UI](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113058) in GitLab 15.10. GitLab can suggest reviewers. Using the changes in a merge request and a project's contribution graph, machine learning suggestions appear in the reviewer section of the right sidebar.  -This feature is currently in [Open Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#open-beta) behind a [feature flag](https://gitlab.com/gitlab-org/gitlab/-/issues/368356). - For more information, see [Data usage in Suggested Reviewers](data_usage.md). ### Enable suggested reviewers @@ -84,7 +87,7 @@ To download the changes included in a merge request as a diff: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**. 1. Select your merge request. -1. In the upper right, select **Code > Plain diff**. +1. In the upper-right corner, select **Code > Plain diff**. If you know the URL of the merge request, you can also download the diff from the command line by appending `.diff` to the URL. This example downloads the diff @@ -107,7 +110,7 @@ To download the changes included in a merge request as a patch file: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**. 1. Select your merge request. -1. In the upper right, select **Code > Email patches**. +1. In the upper-right corner, select **Code > Patches**. If you know the URL of the merge request, you can also download the patch from the command line by appending `.patch` to the URL. This example downloads the patch @@ -172,7 +175,7 @@ If you have a review in progress, you can also add a comment from the **Overview When editing the **Reviewers** field in a new or existing merge request, GitLab displays the name of the matching [approval rule](../approvals/rules.md) -below the name of each suggested reviewer. [Code Owners](../../code_owners.md) are displayed as `Codeowner` without group detail. +below the name of each suggested reviewer. [Code Owners](../../codeowners/index.md) are displayed as `Codeowner` without group detail. This example shows reviewers and approval rules when creating a new merge request: @@ -234,7 +237,7 @@ When bulk-editing merge requests in a project, you can edit the following attrib To update multiple project merge requests at the same time: 1. In a project, go to **Merge requests**. -1. Select **Edit merge requests**. A sidebar on the right-hand side of your screen appears with +1. Select **Bulk edit**. A sidebar on the right-hand side of your screen appears with editable fields. 1. Select the checkboxes next to each merge request you want to edit. 1. Select the appropriate fields and their values from the sidebar. @@ -254,7 +257,7 @@ When bulk editing merge requests in a group, you can edit the following attribut To update multiple group merge requests at the same time: 1. In a group, go to **Merge requests**. -1. Select **Edit merge requests**. A sidebar on the right-hand side of your screen appears with +1. Select **Bulk edit**. A sidebar on the right-hand side of your screen appears with editable fields. 1. Select the checkboxes next to each merge request you want to edit. 1. Select the appropriate fields and their values from the sidebar. @@ -424,3 +427,4 @@ than 1000. The cached value is rounded to thousands (or millions) and updated ev ## Related topics - [Merge methods](../methods/index.md) +- [Draft Notes API](../../../../api/draft_notes.md) diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 668dece9fda..9187c5fad44 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -8,156 +8,176 @@ type: index, reference # Suggest changes **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) custom commit messages for suggestions in GitLab 13.9 [with a flag](../../../../administration/feature_flags.md) named `suggestions_custom_commit`. Disabled by default. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10. - -As a reviewer, you're able to suggest code changes with a Markdown syntax in merge request -diff threads. Then, the merge request author (or other users with appropriate -[permission](../../../permissions.md)) can apply these suggestions. -This action generates a commit in the merge request, authored by the user that suggested the changes. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10. Feature flag `suggestions_custom_commit` removed. + +Reviewers can suggest code changes with a Markdown syntax in merge request diff threads. +The merge request author (or other users with the appropriate role) can apply any or +all of the suggestions from the GitLab UI. Applying suggestions adds a commit to the +merge request, authored by the user who suggested the changes. + +## Create suggestions + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the secondary menu, select **Changes**. +1. Find the lines of code you want to change. + - To select a single line: + - Hover over the line number, and + select **Add a comment to this line** (**{comment}**). + - To select multiple lines: + 1. Hover over the line number, and select **Add a comment to this line** (**{comment}**). + 1. Select and drag your selection until all desired lines are included. To + learn more, see [Multi-line suggestions](#multi-line-suggestions). +1. In the comment toolbar, select **Insert suggestion** (**{doc-code}**). GitLab + inserts a pre-populated code block into your comment, like this: + + ````markdown + ```suggestion:-0+0 + The content of the line you selected is shown here. + ``` + ```` + +1. Edit the pre-populated code block to add your suggestion. +1. Select either **Start a review** or **Add to review** to add your comment to a + [review](index.md), or **Add comment now** to add the comment to the thread immediately. -1. Choose a line of code to be changed, add a new comment, then select - the **Insert suggestion** icon in the toolbar: +### Multi-line suggestions -  +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/232339) in GitLab 13.11: suggestions in multi-line comments also become multi-line. -1. In the comment, add your suggestion to the pre-populated code block: +When you review a merge request diff, you can propose changes to multiple lines (up to 200) +in a single suggestion, by either: -  +- Selecting and dragging, as described in [Create suggestions](#create-suggestions). + GitLab creates a suggestion block for you. +- Selecting a single line, then manually adjusting the range offsets. -1. Select either **Start a review** or **Add to review** to add your comment to a - [review](index.md), or **Add comment now** to add the comment to the thread immediately. +The range offsets in the first line of the suggestion describe line numbers relative +to the line you selected. The offsets specify the lines your suggestion intends to replace. +For example, this suggestion covers 3 lines above and 4 lines below the +commented line: - The suggestion in the comment can be applied by the merge request author - directly from the merge request: +````markdown +```suggestion:-3+4 + "--talk-name=ca.desrt.dconf", + "--socket=wayland", +``` +```` -  +When applied, the suggestion replaces from 3 lines above to 4 lines below the commented line: -1. Optionally specify a custom commit message for individual suggestions (GitLab 13.9 and later) to - describe your change. If you don't specify it, the default commit message is used. + -  +Suggestions for multiple lines are limited to 100 lines _above_ and 100 +lines _below_ the commented diff line. This allows for up to 200 changed lines per +suggestion. -After the author applies a suggestion: +## Apply suggestions -1. The suggestion is marked as **Applied**. -1. The thread is resolved. -1. GitLab creates a new commit with the changes. -1. If the user has the Developer role, GitLab pushes - the suggested change directly into the codebase in the merge request's branch. +Prerequisites: -## Multi-line suggestions +- You must be the author of the merge request, or have at least the Developer role in the project. -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/232339) in GitLab 13.11: suggestions in multi-line comments also become multi-line. +To apply suggested changes directly from the merge request: -Reviewers can also suggest changes to multiple lines with a single suggestion -within merge request diff threads by selecting and dragging selection to all -relevant line numbers or by adjusting the range offsets. The -offsets are relative to the position of the diff thread, and specify the -range to be replaced by the suggestion when it is applied. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find your merge request. +1. Find the comment containing the suggestion you want to apply. + - To apply suggestions individually, select **Apply suggestion**. + - To apply multiple suggestions in a single commit, select **Add suggestion to batch**. +1. Optional. Provide a custom commit message to describe your change. If you don't provide a custom message, the default commit message is used. +1. Select **Apply**. - +After a suggestion is applied: -In the previous example, the suggestion covers three lines above and four lines -below the commented line. When applied, it would replace from 3 lines _above_ -to 4 lines _below_ the commented line, with the suggested change. +- The suggestion is marked as **Applied**. +- The comment thread is resolved. +- GitLab creates a new commit with the changes. +- If the user has the Developer role, GitLab pushes + the suggested change directly into the codebase in the merge request's branch. - - -NOTE: -Suggestions for multiple lines are limited to 100 lines _above_ and 100 -lines _below_ the commented diff line. This allows for up to 200 changed lines per -suggestion. - -## Code block nested in suggestions +## Nest code blocks in suggestions To add a suggestion that includes a [fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion in four backticks instead of three: -~~~markdown +`````markdown ````suggestion:-0+2 ```shell git config --global receive.advertisepushoptions true ``` ```` -~~~ +`````  ## Configure the commit message for applied suggestions -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13086) in GitLab 12.7. +GitLab uses a default commit message when applying suggestions. This message +supports placeholders, and can be changed. For example, the default message +`Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)` renders +like this if you apply three suggestions to two different files: -GitLab uses a default commit message -when applying suggestions: `Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)` - -<!-- vale gitlab.BadPlurals = NO --> +```plaintext +Apply 3 suggestion(s) to 2 file(s) +``` -For example, consider that a user applied 3 suggestions to 2 different files, the -default commit message is: **Apply 3 suggestion(s) to 2 file(s)** +Merge requests created from forks use the template defined in the target project. -<!-- vale gitlab.BadPlurals = YES --> +To meet your project's needs, you can customize these messages and include other +placeholder variables: -These commit messages 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 suggestions** text: +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. +1. Scroll to **Merge suggestions**, and alter the text to meet your needs. + See [Supported variables](#supported-variables) for a list of placeholders + you can use in this message. - +### Supported variables -You can also use following variables besides static text: +The template for commit messages for applied suggestions supports these variables: | Variable | Description | Output example | |------------------------|-------------|----------------| | `%{branch_name}` | The name of the branch to which suggestions were applied. | `my-feature-branch` | -| `%{files_count}` | The number of files to which suggestions were applied.| **2** | +| `%{files_count}` | The number of files to which suggestions were applied.| `2` | | `%{file_paths}` | The paths of the file to which suggestions were applied. Paths are separated by commas.| `docs/index.md, docs/about.md` | | `%{project_path}` | The project path. | `my-group/my-project` | -| `%{project_name}` | The human-readable name of the project. | **My Project** | -| `%{suggestions_count}` | The number of suggestions applied.| **3** | +| `%{project_name}` | The human-readable name of the project. | `My Project` | +| `%{suggestions_count}` | The number of suggestions applied.| `3` | | `%{username}` | The username of the user applying suggestions. | `user_1` | -| `%{user_full_name}` | The full name of the user applying suggestions. | **User 1** | +| `%{user_full_name}` | The full name of the user applying suggestions. | `User 1` | For example, to customize the commit message to output -**Addresses user_1's review**, set the custom text to +`Addresses user_1's review`, set the custom text to `Addresses %{username}'s review`. -For merge requests created from forks, GitLab uses the template defined in target project. - -NOTE: -Custom commit messages for each applied suggestion is -introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). - ## Batch suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](../../../../policy/alpha-beta-support.md#alpha-features) with a flag named `batch_suggestions`, disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [Experiment](../../../../policy/alpha-beta-support.md#experiment) with a flag named `batch_suggestions`, disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. [Feature flag `batch_suggestions`](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) removed. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) custom commit messages for batch suggestions in GitLab 14.4. -You can apply multiple suggestions at once to reduce the number of commits added -to your branch to address your reviewers' requests. - -1. To start a batch of suggestions to apply with a single commit, select **Add suggestion to batch**: - -  - -1. Add as many additional suggestions to the batch as you wish: - -  - -1. To remove suggestions, select **Remove from batch**: - -  +To reduce the number of commits added to your branch, you can apply multiple +suggestions in a single commit. -1. Having added all the suggestions to your liking, when ready, select **Apply suggestions**. You - can optionally specify a custom commit message for [batch suggestions](#batch-suggestions) - (GitLab 14.4 and later) to describe your change. If you don't specify it, the default commit - message is used. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find your merge request. +1. For each suggestion you want to apply, and select **Add suggestion to batch**. +1. Optional. To remove a suggestion, select **Remove from batch**. +1. After you add your desired suggestions, select **Apply suggestions**. -  + WARNING: + If you apply a batch of suggestions containing changes from multiple authors, + you are credited as the resulting commit's author. If your project is configured + to [prevent approvals from users who add commits](../approvals/settings.md#prevent-approvals-by-users-who-add-commits), you are no longer an eligible + approver for this merge request. -WARNING: -Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions. +1. Optional. Provide a custom commit message for [batch suggestions](#batch-suggestions) + (GitLab 14.4 and later) to describe your change. If you don't specify one, + the default commit message is used. ## Related topics diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 9f87f1e2e0d..075716e90c8 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -33,7 +33,14 @@ squash commits and merge commits. ## Set default squash options for a merge request Users with permission to create or edit a merge request can set the default squash options -for a merge request. To do this: +for a merge request. + +Prerequisites: + +- Your project must be [configured](#configure-squash-options-for-a-project) to allow or + encourage squashing. + +To do this: 1. Go to the merge request and select **Edit**. 1. Select or clear the **Squash commits when merge request is accepted** checkbox. @@ -58,6 +65,10 @@ squash the commits as part of the merge process: > - [Enabled on GitLab.com and self-managed by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39382) in GitLab 13.3. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/232536) in GitLab 13.8. Feature flag `squash_options` removed. +Prerequisites: + +- You must have at least the Maintainer role for this project. + To configure the default squashing behavior for all merge requests in your project: 1. On the top bar, select **Main menu > Projects** and find your project. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 62a2baa049b..0e339c65ed5 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -3,7 +3,6 @@ stage: Govern group: Compliance info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference, concepts -disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/status_checks.html' --- # External status checks **(ULTIMATE)** @@ -12,6 +11,8 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/statu > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320783) in GitLab 14.1. > - `failed` status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329636) in GitLab 14.9. +Status checks are API calls to external systems that request the status of an external requirement. + You can create a status check that sends merge request data to third-party tools. When users create, change, or close merge requests, GitLab sends a notification. The users or automated workflows can then update the status of merge requests from outside of GitLab. @@ -70,7 +71,7 @@ using the API. You don't need to wait for a merge request webhook payload to be ## View the status checks on a project -Within each project's settings, you can see a list of status checks added to the project: +Within each project's settings, you can see a list of status check services added to the project: 1. In your project, go to **Settings > Merge requests** section. 1. Scroll down to **Status checks**. @@ -80,9 +81,9 @@ Within each project's settings, you can see a list of status checks added to the This list shows the service name, API URL, and targeted branch. It also provides actions to allow you to create, edit, or remove status checks. -## Add or update a status check +## Add or update a status check service -### Add a status check +### Add a status check service Within the **Status checks** sub-section, select the **Add status check** button. The **Add status check** form is then shown. @@ -91,7 +92,7 @@ The **Add status check** form is then shown. Filling in the form and selecting the **Add status check** button creates a new status check. -### Update a status check +### Update a status check service Within the **Status checks** sub-section, select the **Edit** button next to the status check you want to edit. @@ -134,7 +135,7 @@ for doesn't appear immediately. The search box requires If you want the status check to be applied to **all** merge requests, you can select the **All branches** option. -## Delete a status check +## Delete a status check service Within the **Status checks** sub-section, select the **Remove...** button next to the status check you want to delete. @@ -151,12 +152,15 @@ the status check and it **is not** recoverable. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327634) in GitLab 14.1. > - UI [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91504) in GitLab 15.2. > - Ability to retry failed external status checks [added](https://gitlab.com/gitlab-org/gitlab/-/issues/383200) in GitLab 15.8. +> - Widget [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111763) to poll for updates when there are pending status checks in GitLab 15.11. The status checks widget displays in merge requests and displays the following statuses: - **pending** (**{status-neutral}**), while GitLab waits for a response from an external status check. - **success** (**{status-success}**) or **failed** (**{status-failed}**), when GitLab receives a response from an external status check. +When there are pending status checks, the widget polls for updates every few seconds until it receives a **success** or **failed** response. + To retry a failed status check: 1. Expand the merge request widget to show the list of external status checks. diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 81b334c0a02..c7ed6069cb6 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -137,14 +137,16 @@ To switch between the two settings, select either **Issues** or **Issue weight** When sorting by weight, make sure all your issues have weight assigned, because issues with no weight don't show on the chart. -<!-- ## Troubleshooting +## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +### Burndown and burnup charts do not show the correct issue status -Each scenario can be a third-level heading, for example `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +A limitation of these charts is that [the days are in the UTC time zone](https://gitlab.com/gitlab-org/gitlab/-/issues/267967). + +This can cause the graphs to be inaccurate in other timezones. For example: + +- All the issues in a milestone are recorded as being closed on or before the last day. +- One issue was closed on the last day at 6 PM PST (Pacific time), which is UTC-7. +- The issue activity log displays the closure time at 6 PM on the last day of the milestone. +- The charts plot the time in UTC, so for this issue, the close time is 1 AM the following day. +- The charts show the milestone as incomplete and missing one closed issue. diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 5f9a2961df5..4641af262ca 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -65,7 +65,10 @@ Improving this experience is tracked in issue [339009](https://gitlab.com/gitlab You can view all the milestones you have access to in the entire GitLab namespace. You might not see some milestones because they're in projects or groups you're not a member of. -To do so, on the top bar select **Main menu > Milestones**. +To do so: + +1. On the top bar select **Main menu > Your work**. +1. On the left sidebar, select **Milestones**. ### View milestone details @@ -139,7 +142,7 @@ To edit a milestone: 1. On the top bar, select **Main menu > Projects** and find your project or **Main menu > Groups** and find your group. 1. Select a milestone's title. -1. Select **Edit**. +1. In the top right corner, select **Milestone actions** (**{ellipsis_v}**) and then select **Edit**. 1. Edit the title, start date, due date, or description. 1. Select **Save changes**. @@ -155,7 +158,7 @@ To edit a milestone: 1. On the top bar, select **Main menu > Projects** and find your project or **Main menu > Groups** and find your group. 1. Select a milestone's title. -1. Select **Delete**. +1. In the top right corner, select **Milestone actions** (**{ellipsis_v}**) and then select **Delete**. 1. Select **Delete milestone**. ## Promote a project milestone to a group milestone @@ -182,7 +185,7 @@ To promote a project milestone: 1. On the left sidebar, select **Issues > Milestones**. 1. Either: - Select **Promote to Group Milestone** (**{level-up}**) next to the milestone you want to promote. - - Select the milestone title, and then select **Promote**. + - Select the milestone title, and then select **Milestone actions** (**{ellipsis_v}**) > **Promote**. 1. Select **Promote Milestone**. ## Assign a milestone to an issue or merge request diff --git a/doc/user/project/ml/experiment_tracking/img/candidate_v15_11.png b/doc/user/project/ml/experiment_tracking/img/candidate_v15_11.png Binary files differnew file mode 100644 index 00000000000..50bcd1e8479 --- /dev/null +++ b/doc/user/project/ml/experiment_tracking/img/candidate_v15_11.png diff --git a/doc/user/project/ml/experiment_tracking/img/candidate_v15_7.png b/doc/user/project/ml/experiment_tracking/img/candidate_v15_7.png Binary files differdeleted file mode 100644 index fb2e2e706d6..00000000000 --- a/doc/user/project/ml/experiment_tracking/img/candidate_v15_7.png +++ /dev/null diff --git a/doc/user/project/ml/experiment_tracking/img/candidates_v15_11.png b/doc/user/project/ml/experiment_tracking/img/candidates_v15_11.png Binary files differnew file mode 100644 index 00000000000..3a2944c92ae --- /dev/null +++ b/doc/user/project/ml/experiment_tracking/img/candidates_v15_11.png diff --git a/doc/user/project/ml/experiment_tracking/img/candidates_v15_7.png b/doc/user/project/ml/experiment_tracking/img/candidates_v15_7.png Binary files differdeleted file mode 100644 index 58dfe94a108..00000000000 --- a/doc/user/project/ml/experiment_tracking/img/candidates_v15_7.png +++ /dev/null diff --git a/doc/user/project/ml/experiment_tracking/img/experiments_v15_11.png b/doc/user/project/ml/experiment_tracking/img/experiments_v15_11.png Binary files differnew file mode 100644 index 00000000000..f7e25c1a0f1 --- /dev/null +++ b/doc/user/project/ml/experiment_tracking/img/experiments_v15_11.png diff --git a/doc/user/project/ml/experiment_tracking/img/experiments_v15_7.png b/doc/user/project/ml/experiment_tracking/img/experiments_v15_7.png Binary files differdeleted file mode 100644 index a7d4a3e559f..00000000000 --- a/doc/user/project/ml/experiment_tracking/img/experiments_v15_7.png +++ /dev/null diff --git a/doc/user/project/ml/experiment_tracking/index.md b/doc/user/project/ml/experiment_tracking/index.md index a7096d633a0..a2c2ab0cc40 100644 --- a/doc/user/project/ml/experiment_tracking/index.md +++ b/doc/user/project/ml/experiment_tracking/index.md @@ -4,78 +4,85 @@ group: Incubation info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering program. No technical writer assigned to this group. --- -# Machine Learning Experiment Tracking **(FREE)** +# Machine learning model experiments **(FREE)** -DISCLAIMER: -Machine Learning Experiment Tracking is an experimental feature being developed by the Incubation Engineering Department, -and will receive significant changes over time. This feature is being release with the aim of getting user feedback, but -is not stable and can lead to performance degradation. See below on how to disable this feature. +FLAG: +On self-managed GitLab, model experiment tracking is disabled by default. +To enable the feature, ask an administrator to [enable the feature flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. +On GitLab.com, this feature is in private testing only. -When creating machine learning models, data scientists often experiment with different parameters, configurations, feature -engineering, and so on, to improve the performance of the model. Keeping track of all this metadata and the associated +NOTE: +Model experiment tracking is an [experimental feature](../../../../policy/alpha-beta-support.md). Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. + +When creating machine learning models, data scientists often experiment with different parameters, configurations, and feature +engineering to improve the performance of the model. Keeping track of all this metadata and the associated artifacts so that the data scientist can later replicate the experiment is not trivial. Machine learning experiment tracking enables them to log parameters, metrics, and artifacts directly into GitLab, giving easy access later on. - +These features have been proposed: - +- Searching experiments. +- Visual comparison of candidates. +- Creating, deleting, and updating candidates through the GitLab UI. - +For feature requests, see [epic 9341](https://gitlab.com/groups/gitlab-org/-/epics/9341). ## What is an experiment? -An experiment is a collection of comparable model candidates. Experiments can be long lived (for example, when they represent -a use case), or short lived (results from hyperparameter tuning triggered by a merge request), but usually hold model candidates -that have a similar set of parameters and metrics. +In a project, an experiment is a collection of comparable model candidates. +Experiments can be long-lived (for example, when they represent a use case), or +short-lived (results from hyperparameter tuning triggered by a merge request), +but usually hold model candidates that have a similar set of parameters measured +by the same metrics. + + ## Model candidate A model candidate is a variation of the training of a machine learning model, that can be eventually promoted to a version -of the model. The goal of a data scientist is to find the model candidate whose parameter values lead to the best model +of the model. + + + +The goal of a data scientist is to find the model candidate whose parameter values lead to the best model performance, as indicated by the given metrics. -Example parameters: + + +Some example parameters: -- Algorithm (linear regression, decision tree, and so on). +- Algorithm (such as linear regression or decision tree). - Hyperparameters for the algorithm (learning rate, tree depth, number of epochs). - Features included. -## Usage +## Track new experiments and candidates -### User access management +Experiment and trials can only be tracked through the +[MLflow](https://www.mlflow.org/docs/latest/tracking.html) client integration. +See [MLflow client integration](../../integrations/mlflow_client.md) for more information +on how to use GitLab as a backend for the MLflow Client. -An experiment is always associated to a project. Only users with access to the project an experiment is associated with -can view that experiment data. +## Explore model candidates -### Tracking new experiments and trials +Prerequisites: -Experiment and trials can only be tracked through the [MLFlow](https://www.mlflow.org/docs/latest/tracking.html) client -integration. More information on how to use GitLab as a backend for MLFlow Client can be found [at the documentation page](../../integrations/mlflow_client.md). +- You must have at least the Developer role to view experiment data. -### Exploring model candidates +To list the current active experiments, either go to `https/-/ml/experiments` or: -To list the current active experiments, navigate to `https/-/ml/experiments`. To display all trials -that have been logged, along with their metrics and parameters, select an experiment. To display details for a candidate, -select **Details**. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Packages & registries > Model experiments**. +1. To display all candidates that have been logged, along with their metrics, parameters, and metadata, select an experiment. +1. To display details for a candidate, select **Details**. -### Logging artifacts +## View log artifacts Trial artifacts are saved as [generic packages](../../../packages/generic_packages/index.md), and follow all their -conventions. After an artifact is logged for a candidate, all artifacts logged for the candidate are listed in the -package registry. The package name for a candidate is `ml_candidate_<candidate_id>`, with version `-`. The link to the -artifacts can also be accessed from the **Experiment Candidates** list or **Candidate detail**. - -### Limitations and future - -- Searching experiments, searching trials, visual comparison of trials, and creating, deleting and updating experiments and trials through GitLab UI is under development. - -## Disabling or enabling the Feature - -On self-managed GitLab, ML Experiment Tracking is disabled by default. To enable the feature, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. -On GitLab.com, this feature is currently on private testing. - -## Feedback, roadmap and reports +limitations. After an artifact is logged for a candidate, all artifacts logged for the candidate are listed in the +package registry. The package name for a candidate is `ml_experiment_<experiment_id>`, where the version is the candidate +IID. The link to the artifacts can also be accessed from the **Experiment Candidates** list or **Candidate detail**. -For updates on the development, refer to the [development epic](https://gitlab.com/groups/gitlab-org/-/epics/8560). +## Related topics -For feedback, bug reports and feature requests, refer to the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/381660). +- Development details in [epic 8560](https://gitlab.com/groups/gitlab-org/-/epics/8560). +- Add feedback in [issue 381660](https://gitlab.com/gitlab-org/gitlab/-/issues/381660). diff --git a/doc/user/project/organize_work_with_projects.md b/doc/user/project/organize_work_with_projects.md index 2b4ce6d2fd0..85a1dfda679 100644 --- a/doc/user/project/organize_work_with_projects.md +++ b/doc/user/project/organize_work_with_projects.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Organization +stage: Data Stores +group: Tenant Scale info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- 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 e55cf337d16..5cdf493fe6f 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -1,14 +1,11 @@ --- type: concepts -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# DNS records overview **(FREE)** - -_Read this document for a brief overview of DNS records in the scope -of GitLab Pages, for beginners in web development._ +# GitLab Pages DNS records **(FREE)** A Domain Name System (DNS) web service routes visitors to websites by translating domain names (such as `www.example.com`) into the @@ -74,7 +71,7 @@ Example: This way, visitors visiting `www.example.com` are redirected to `example.com`. -## MX record +## `MX` record MX records are used to define the mail exchanges that are used for the domain. This helps email messages arrive at your mail server correctly. 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 24e9e6e15a4..a97fc1171fc 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -1,11 +1,10 @@ --- -disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html' -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Custom domains and SSL/TLS certificates **(FREE)** +# GitLab Pages custom domains **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238461) in GitLab 15.4, you can use verified domains to [bypass user email confirmation for SAML- or SCIM-provisioned users](../../../group/saml_sso/index.md#bypass-user-email-confirmation-with-verified-domains). @@ -13,7 +12,7 @@ You can use custom domains: - With GitLab Pages. - To [bypass user email confirmation for SAML- or SCIM-provisioned users](../../../group/saml_sso/index.md#bypass-user-email-confirmation-with-verified-domains). - When using custom domains this way, you use the GitLab Pages feature but can skip the [requirements](#requirements). + When using custom domains this way, you use the GitLab Pages feature but can skip the [prerequisites](#prerequisites). To use one or more custom domain names: @@ -24,7 +23,7 @@ To use one or more custom domain names: To set up Pages with a custom domain name, read the requirements and steps below. -### Requirements +### Prerequisites - A GitLab Pages website up and running, served under the default Pages domain (`*.gitlab.io`, for GitLab.com). @@ -34,7 +33,7 @@ To set up Pages with a custom domain name, read the requirements and steps below 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). + your [Pages daemon](../../../../administration/pages/index.md#the-gitlab-pages-daemon). If you don't have IPv6, you can omit the IPv6 address. Example: @@ -197,38 +196,6 @@ from the GitLab project. in place. Your domain is periodically reverified, and may be disabled if the record is removed. -##### Troubleshoot domain verification - -To manually verify that you have properly configured the domain verification -`TXT` DNS entry, you can run the following command in your terminal: - -```shell -dig _gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN> TXT -``` - -Expect the output: - -```plaintext -;; ANSWER SECTION: -_gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN>. 300 IN TXT "gitlab-pages-verification-code=<YOUR-VERIFICATION-CODE>" -``` - -In some cases it can help to add the verification code with the same domain name as you are trying to register. - -For a root domain: - -| From | DNS Record | To | -| ------------------------------------------------- | ---------- | ---------------------- | -| `example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -| `_gitlab-pages-verification-code.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | - -For a subdomain: - -| From | DNS Record | To | -| ------------------------------------------------- | ---------- | ---------------------- | -| `www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -| `_gitlab-pages-verification-code.www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | - ### Add more domain aliases You can add more than one alias (custom domains and subdomains) to the same project. @@ -352,14 +319,36 @@ To enable this setting: If you use Cloudflare CDN in front of GitLab Pages, make sure to set the SSL connection setting to `full` instead of `flexible`. For more details, see the [Cloudflare CDN directions](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef). -<!-- ## Troubleshooting +## Troubleshooting + +### Domain verification + +To manually verify that you have properly configured the domain verification +`TXT` DNS entry, you can run the following command in your terminal: + +```shell +dig _gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN> TXT +``` + +Expect the output: + +```plaintext +;; ANSWER SECTION: +_gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN>. 300 IN TXT "gitlab-pages-verification-code=<YOUR-VERIFICATION-CODE>" +``` + +In some cases it can help to add the verification code with the same domain name as you are trying to register. -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +For a root domain: -Each scenario can be a third-level heading, for example, `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +| From | DNS Record | To | +| ------------------------------------------------- | ---------- | ---------------------- | +| `example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | + +For a subdomain: + +| From | DNS Record | To | +| ------------------------------------------------- | ---------- | ---------------------- | +| `www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | 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 95ac2e50f29..91633e01ad2 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -1,12 +1,12 @@ --- type: reference description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Pages integration with Let's Encrypt **(FREE)** +# GitLab Pages Let's Encrypt certificates **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28996) in GitLab 12.1. @@ -21,7 +21,7 @@ open source Certificate Authority. WARNING: This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(FREE SELF)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3342). -## Requirements +## Prerequisites Before you can enable automatic provisioning of an SSL certificate for your domain, make sure you have: diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index 398d8dc6e1e..484dc784fdb 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -1,14 +1,11 @@ --- type: concepts -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# SSL/TLS certificates **(FREE)** - -_Read this document for a brief overview of SSL/TLS certificates in -the scope of GitLab Pages, for beginners in web development._ +# GitLab Pages SSL/TLS certificates **(FREE)** Every GitLab Pages project on GitLab.com is available under HTTPS for the default Pages domain (`*.gitlab.io`). Once you set diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index f596e418b02..17618146350 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -1,11 +1,11 @@ --- type: reference, howto -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Create a Pages website by using a CI/CD template **(FREE)** +# Create a GitLab Pages website from a CI/CD template **(FREE)** GitLab provides `.gitlab-ci.yml` templates for the most popular Static Site Generators (SSGs). You can create your own `.gitlab-ci.yml` file from one of these templates, and run @@ -37,4 +37,4 @@ For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. To view the HTML and other assets that were created for the site, -[download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +[download the job artifacts](../../../../ci/jobs/job_artifacts.md#download-job-artifacts). 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 509609e9b89..e8de80ac137 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -1,11 +1,11 @@ --- type: reference, howto -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Create a Pages website from a forked sample **(FREE)** +# Create a GitLab Pages website from a forked sample project **(FREE)** GitLab provides [sample projects for the most popular Static Site Generators (SSG)](https://gitlab.com/pages). You can fork one of the sample projects and run the CI/CD pipeline to generate a Pages website. @@ -18,8 +18,8 @@ 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. Select the name of the project you want to [fork](../../repository/forking_workflow.md#creating-a-fork). -1. In the upper right, select **Fork** and then choose a namespace to fork to. +1. Select the name of the project you want to [fork](../../repository/forking_workflow.md#create-a-fork). +1. In the upper-right corner, select **Fork**, 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. @@ -65,4 +65,4 @@ you can rename it to `<namespace>.gitlab.io`, where `<namespace>` is your GitLab ## Related topics -- [Download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts) +- [Download the job artifacts](../../../../ci/jobs/job_artifacts.md#download-job-artifacts) 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 a3d6c8f75f9..c62ead69216 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -423,16 +423,11 @@ Now GitLab CI/CD not only builds the website, but also: - **Continuously deploys** every push to the `main` branch. To view the HTML and other assets that were created for the site, -[download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +[download the job artifacts](../../../../ci/jobs/job_artifacts.md#download-job-artifacts). ## Related topics -For more information, see the following blog posts. - -- Use GitLab CI/CD `environments` to - [deploy your web app to staging and production](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). -- Learn how to run jobs - [sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2020/12/10/basics-of-gitlab-ci-updated/). -- Learn [how to pull specific directories from different projects](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) - to deploy this website, <https://docs.gitlab.com>. -- Learn [how to use GitLab Pages to produce a code coverage report](https://about.gitlab.com/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/). +- [Deploy your web app to staging and production](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/) +- [Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2020/12/10/basics-of-gitlab-ci-updated/) +- [Pull specific directories from different projects](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) +- [Use GitLab Pages to produce a code coverage report](https://about.gitlab.com/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/) diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index a301d2b64be..cb1da3fb21f 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -1,10 +1,10 @@ --- -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Create a Pages website from a template **(FREE)** +# Create a GitLab Pages website from a project template **(FREE)** GitLab provides templates for the most popular Static Site Generators (SSGs). You can create a new project from a template and run the CI/CD pipeline to generate a Pages website. @@ -32,4 +32,4 @@ For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. To view the HTML and other assets that were created for the site, -[download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +[download the job artifacts](../../../../ci/jobs/job_artifacts.md#download-job-artifacts). diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index 91c2c532a9a..00635fe6db2 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -4,7 +4,7 @@ group: Incubation info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Create a Pages deployment for your static site **(FREE)** +# Create a GitLab Pages deployment for a static site **(FREE)** If you already have a GitLab project that contains your static site or framework, you can generate a GitLab Pages website from it. diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index a0c8073d6eb..6eb996db210 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,10 +1,10 @@ --- -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Pages domain names, URLs, and base URLs **(FREE)** +# GitLab Pages default domain names and URLs **(FREE)** On this document, learn how to name your project for GitLab Pages according to your intended website's URL. diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 691757e3eca..a68ad604989 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -1,7 +1,7 @@ --- description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.' -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -126,6 +126,13 @@ If you are running a self-managed instance of GitLab, <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=dD8c7WNcc6s) about how to get started with GitLab Pages administration. +### Configure GitLab Pages in a Helm Chart (Kubernetes) instance + +To configure GitLab Pages on instances deployed via Helm chart (Kubernetes), use either: + +- [The `gitlab-pages` subchart](https://docs.gitlab.com/charts/charts/gitlab/gitlab-pages/). +- [An external GitLab Pages instance](https://docs.gitlab.com/charts/advanced/external-gitlab-pages/). + ## Security for GitLab Pages If your username is `example`, your GitLab Pages website is located at `example.gitlab.io`. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 51c42eeecb8..05d0b461fea 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,10 +1,10 @@ --- -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Exploring GitLab Pages **(FREE)** +# GitLab Pages settings **(FREE)** This document is a user guide to explore the options and settings GitLab Pages offers. @@ -271,7 +271,7 @@ This problem most likely results from a missing `index.html` file in the public a 404 is encountered, confirm that the public directory contains an `index.html` file. If the file contains a different name such as `test.html`, the Pages site can still be accessed, but the full path would be needed. For example: `https//group-name.pages.example.com/project-name/test.html`. -The contents of the public directory can be confirmed by [browsing the artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts) from the latest pipeline. +The contents of the public directory can be confirmed by [browsing the artifacts](../../../ci/jobs/job_artifacts.md#download-job-artifacts) from the latest pipeline. Files listed under the public directory can be accessed through the Pages URL for the project. diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 248a74a8abc..1b046d03f59 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index 751db136e34..6ee8ea17aee 100644 --- a/doc/user/project/pages/public_folder.md +++ b/doc/user/project/pages/public_folder.md @@ -1,12 +1,12 @@ --- description: 'Learn how to configure the build output folder for the most common static site generators' -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Configure the public files folder **(FREE)** +# GitLab Pages public folder **(FREE)** All the files that should be accessible by the browser must be in a root-level folder called `public`. @@ -91,14 +91,37 @@ NOTE: GitLab Pages supports only static sites. For Next.js, you can use Next's [Static HTML export functionality](https://nextjs.org/docs/advanced-features/static-html-export). -Use the `-o public` flag after `next export` as the build command, for -example: +With the release of [Next.js 13](https://nextjs.org/blog/next-13) a lot has changed on how Next.js works. +It is recommended to use the following `next.config.js` so all static assets can be exported properly: -```shell -next export -o public +```javascript +/** @type {import('next').NextConfig} */ +const nextConfig = { + reactStrictMode: true, + images: { + unoptimized: true, + }, + assetPrefix: "https://example.gitlab.io/namespace-here/my-gitlab-project/" +} + +module.exports = nextConfig +``` + +An example `.gitlab-ci.yml` can be as minimal as: + +```yaml +pages: + before_script: + - npm install + script: + - npm run build + - mv out/* public + artifacts: + paths: + - public ``` -### Nuxt.js +## Nuxt.js NOTE: GitLab Pages supports only static sites. @@ -146,7 +169,7 @@ module.exports = { ## Should you commit the `public` folder? Not necessarily. However, when the GitLab Pages deploy pipeline runs, it looks -for an [artifact](../../../ci/pipelines/job_artifacts.md) of that name. +for an [artifact](../../../ci/jobs/job_artifacts.md) of that name. If you set up a job that creates the `public` folder before deploy, such as by running `npm run build`, committing the folder isn't required. diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index f5447fd67ca..bd8206b3bda 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -1,10 +1,10 @@ --- -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Create redirects for GitLab Pages **(FREE)** +# GitLab Pages redirects **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4 behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/367) in GitLab 13.5. diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index da53fe2f5e9..1d279436d2c 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -22,12 +22,14 @@ The [default branch](repository/branches/default.md) for your repository is prot ## Who can modify a protected branch +> Branch push permission [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118532) to require GitLab administrators to also have the **allowed** permission in GitLab 16.0. + When a branch is protected, the default behavior enforces these restrictions on the branch. | Action | Who can do it | |:-------------------------|:------------------------------------------------------------------| | Protect a branch | At least the Maintainer role. | -| Push to the branch | GitLab administrators and anyone with **Allowed** permission. (1) | +| Push to the branch | Anyone with **Allowed** permission. (1) | | Force push to the branch | No one. | | Delete the branch | No one. (2) | @@ -36,6 +38,40 @@ When a branch is protected, the default behavior enforces these restrictions on 1. No one can delete a protected branch using Git commands, however, users with at least Maintainer role can [delete a protected branch from the UI or API](#delete-a-protected-branch). +### When a branch matches multiple rules + +When a branch matches multiple rules, the **most permissive rule** determines the +level of protection for the branch. For example, consider these rules, which include +[wildcards](#configure-multiple-protected-branches-by-using-a-wildcard): + +| Branch name pattern | Allowed to merge | Allowed to push and merge | +|---------------------|------------------------|-----------------| +| `v1.x` | Maintainer | Maintainer | +| `v1.*` | Maintainer + Developer | Maintainer | +| `v*` | No one | No one | + +A branch named `v1.x` matches all three branch name patterns: `v1.x`, `v1.*`, and `v*`. +As the most permissive option determines the behavior, the resulting permissions for branch `v1.x` are: + +- **Allowed to merge:** Of the three settings, `Maintainer + Developer` is most permissive, + and controls branch behavior as a result. Even though the branch also matched `v1.x` and `v*` + (which each have stricter permissions), users with the Developer role can merge into the branch. +- **Allowed to push and merge:** Of the three settings, `Maintainer` is the most permissive, and controls + branch behavior as a result. Even though branches matching `v*` are set to `No one`, branches + that _also_ match `v1.x` or `v1.*` receive the more permissive `Maintainer` permission. + +To be certain that a rule controls the behavior of a branch, +_all_ other patterns that match must apply less or equally permissive rules. + +If you want to ensure that `No one` is allowed to push to branch `v1.x`, every pattern +that matches `v1.x` must set `Allowed to push and merge` to `No one`, like this: + +| Branch name pattern | Allowed to merge | Allowed to push and merge | +|---------------------|------------------------|-----------------| +| `v1.x` | Maintainer | No one | +| `v1.*` | Maintainer + Developer | No one | +| `v*` | No one | No one | + ### Set the default branch protection level Administrators can set a default branch protection level in the @@ -43,10 +79,41 @@ Administrators can set a default branch protection level in the ## Configure a protected branch +Configure protected branches for all projects in a group, or just for a project. + +### For all projects in a group **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106532) in GitLab 15.9 behind a feature flag, disabled by default. + +Group owners can create protected branches for a group. These settings are inherited by all projects in the group and can't be overridden by project settings. + +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 `group_protected_branches`. On GitLab.com, this feature is not available. + +Prerequisite: + +- You must have the Owner role in the group. + +To protect a branch for all the projects in a group: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Protected branches**. +1. In the **Branch** text box, type the branch name or a wildcard. +1. From the **Allowed to merge** list, select a role that can merge into this branch. +1. From the **Allowed to push and merge** list, select a role that can push to this branch. +1. Select **Protect**. + +The protected branch is added to the list of protected branches. + +### For a project + Prerequisite: - You must have at least the Maintainer role. -- When granting a group **Allowed to merge** or **Allowed to push** permissions +- When granting a group **Allowed to merge** or **Allowed to push and merge** permissions on a protected branch, the group must be added to the project. To protect a branch: @@ -56,7 +123,7 @@ To protect a branch: 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to merge** list, select a role, or group that can merge into this branch. In GitLab Premium, you can also add users. -1. From the **Allowed to push** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. +1. From the **Allowed to push and merge** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. 1. Select **Protect**. The protected branch displays in the list of protected branches. @@ -65,7 +132,7 @@ The protected branch displays in the list of protected branches. If both a specific rule and a wildcard rule apply to the same branch, the most permissive rule controls how the branch behaves. For merge controls to work properly, -set **Allowed to push** to a broader set of users than **Allowed to merge**. +set **Allowed to push and merge** to a broader set of users than **Allowed to merge**. Prerequisite: @@ -86,7 +153,7 @@ To protect multiple branches at the same time: | `*gitlab*` | `gitlab`, `gitlab/staging`, `master/gitlab/production` | 1. From the **Allowed to merge** list, select a role, or group that can merge into this branch. In GitLab Premium, you can also add users. -1. From the **Allowed to push** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. +1. From the **Allowed to push and merge** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. 1. Select **Protect**. The protected branch displays in the list of protected branches. @@ -97,7 +164,7 @@ Users with at least the Developer role can create a protected branch. Prerequisites: -- **Allowed to push** is set to **No one** +- **Allowed to push and merge** is set to **No one** - **Allowed to merge** is set to **Developers**. You can create a protected branch by using the UI or API only. @@ -124,11 +191,7 @@ like the [GitLab workflow](../../topics/gitlab_flow.md). 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to merge** list, select **Developers + Maintainers**. -1. From the **Allowed to push** list, select **No one**. - - NOTE: - Setting a role, group or user as **Allowed to push** also allows those users to merge. - +1. From the **Allowed to push and merge** list, select **No one**. 1. Select **Protect**. ## Allow everyone to push directly to a protected branch @@ -139,7 +202,7 @@ You can allow everyone with write access to push to the protected branch. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. -1. From the **Allowed to push** list, select **Developers + Maintainers**. +1. From the **Allowed to push and merge** list, select **Developers + Maintainers**. 1. Select **Protect**. ## Allow deploy keys to push to a protected branch @@ -167,7 +230,7 @@ To allow a deploy key to push to a protected branch: 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. -1. From the **Allowed to push** list, select the deploy key. +1. From the **Allowed to push and merge** list, select the deploy key. 1. Select **Protect**. Deploy keys are not available in the **Allowed to merge** dropdown list. @@ -186,7 +249,7 @@ To protect a new branch and enable force push: 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. -1. From the **Allowed to push** and **Allowed to merge** lists, select the settings you want. +1. From the **Allowed to push and merge** and **Allowed to merge** lists, select the settings you want. 1. To allow all users with push access to force push, turn on the **Allowed to force push** toggle. 1. To reject code pushes that change files listed in the `CODEOWNERS` file, turn on the **Require approval from code owners** toggle. @@ -203,10 +266,9 @@ Members who can push to this branch can now also force push. ## Require Code Owner approval on a protected branch **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab 12.4. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in GitLab 13.5, users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. This means they can skip merge request approval rules. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in GitLab 13.5, users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. This means they can skip merge request approval rules. -For a protected branch, you can require at least one approval by a [Code Owner](code_owners.md). +For a protected branch, you can require at least one approval by a [Code Owner](codeowners/index.md). To protect a new branch and enable Code Owner's approval: @@ -214,7 +276,7 @@ To protect a new branch and enable Code Owner's approval: 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. -1. From the **Allowed to push** and **Allowed to merge** lists, select the settings you want. +1. From the **Allowed to push and merge** and **Allowed to merge** lists, select the settings you want. 1. Turn on the **Require approval from code owners** toggle. 1. Select **Protect**. @@ -262,6 +324,12 @@ Protected branches can only be deleted by using GitLab either from the UI or API This prevents accidentally deleting a branch through local Git commands or third-party Git clients. +## Related topics + +- [Protected branches API](../../api/protected_branches.md) +- [Branches](repository/branches/index.md) +- [Branches API](../../api/branches.md) + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 152a55d24b7..3af475afa4f 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Protected tags **(FREE)** -Protected tags: +Protected [tags](repository/tags/index.md): - Allow control over who has permission to create tags. - Prevent accidental update or deletion once created. @@ -16,7 +16,7 @@ Each rule allows you to match either: - An individual tag name. - Wildcards to control multiple tags at once. -This feature evolved out of [protected branches](protected_branches.md) +This feature evolved out of [protected branches](protected_branches.md). ## Who can modify a protected tag @@ -27,22 +27,22 @@ By default: ## Configuring protected tags -To protect a tag, you must have at least the Maintainer role. +Prerequisites: -1. Go to the project's **Settings > Repository**. +- You must have at least the Maintainer role for the project. -1. From the **Tag** dropdown list, select the tag you want to protect or type and select **Create wildcard**. In the screenshot below, we chose to protect all tags matching `v*`: - -  - -1. From the **Allowed to create** dropdown list, select users with permission to create - matching tags, and select **Protect**: - -  - -1. After done, the protected tag displays in the **Protected tags** list: - -  +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Protected tags**. +1. To protect a single tag, select **Tag**, then choose your tag from the dropdown list. +1. To protect all tags with names matching a string: + 1. Select **Tag**. + 1. Enter the string to use for tag matching. Wildcards (`*`) are supported. + 1. Select **Create wildcard**. +1. In **Allowed to create** , select either the users or roles that may create protected tags. +1. Select **Protect**. + +The protected tag (or wildcard) displays in the **Protected tags** list. ## Wildcard protected tags @@ -86,6 +86,32 @@ To prevent this problem: Users can still create branches, but not tags, with the protected names. +## Allow deploy keys to create protected tags + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325415) in GitLab 15.11. + +You can permit the owner of a [deploy key](deploy_keys/index.md) to create protected tags. +The deploy key works, even if the user isn't a member of the related project. However, the owner of the deploy +key must have at least read access to the project. + +Prerequisites: + +- The deploy key must be enabled for your project. A project deploy key is enabled by default when + it is created. However, a public deploy key must be + [granted](deploy_keys/index.md#grant-project-access-to-a-public-deploy-key) access to the + project. +- The deploy key must have [write access](deploy_keys/index.md#permissions) to your project + repository. + +To allow a deploy key to create a protected tag: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Protected tags**. +1. From the **Tag** dropdown list, select the tag you want to protect. +1. From the **Allowed to create** list, select the deploy key. +1. Select **Protect**. + ## Delete a protected tag You can manually delete protected tags with the GitLab API, or the @@ -106,6 +132,11 @@ Protected tags can only be deleted by using GitLab either from the UI or API. These protections prevent you from accidentally deleting a tag through local Git commands or third-party Git clients. +## Related topics + +- [Protected Tags API](../../api/protected_tags.md) +- [Tags API](../../api/tags.md) + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 90da47f7995..2c52a5d743a 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -49,113 +49,120 @@ 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 [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more active [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). | -| `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. | -| `/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 @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. | +<!-- Don't prettify this table; it will expand out the last field into illegibility --> + +| Command | Issue | Merge request | Epic | Action | +|:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| +| `/add_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more active [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). +| `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. +| `/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 @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 an emoji reaction. | `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. [In GitLab 14.9 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/31200), mentioning a user at the start of a line created a specific type of to-do item notification. | -| `/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](https://gitlab.com/gitlab-org/gitlab/-/issues/7330) in GitLab 12.0). | -| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear [health status](issues/managing_issues.md#health-status) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | -| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | -| `/clone <path/to/project> [--with_notes]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. | -| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | +| `/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. +| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear [health status](issues/managing_issues.md#health-status) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). +| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. +| `/clone <path/to/project> [--with_notes]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. +| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | `/confidential` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Mark issue or epic as confidential. Support for epics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213741) in GitLab 15.6. | -| `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. | -| `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. | -| `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | -| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to do as done. | -| `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [draft status](merge_requests/drafts.md). Use for toggling the draft status ([deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) in GitLab 15.4.) | -| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. See [Chronic](https://gitlab.com/gitlab-org/ruby/gems/gitlab-chronic#examples) for more examples. | -| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue. Mark as a duplicate of, and related to, issue `<#issue>`. | -| `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | -| `/estimate <time>` or `/estimate_time <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. For more information, see [Time tracking](time_tracking.md). Alias `/estimate_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | -| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | -| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. | -| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). | -| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | -| `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. | +| `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. +| `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. +| `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. +| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to-do item as done. +| `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [draft status](merge_requests/drafts.md). | +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. See [Chronic](https://gitlab.com/gitlab-org/ruby/gems/gitlab-chronic#examples) for more examples. +| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue. Mark as a duplicate of, and related to, issue `<#issue>`. +| `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. +| `/estimate <time>` or `/estimate_time <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. For more information, see [Time tracking](time_tracking.md). Alias `/estimate_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. +| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). +| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. +| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). +| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. +| `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. | `/link` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a link and description to [linked resources](../../operations/incident_management/linked_resources.md) in an incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374964) in GitLab 15.5). | -| `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). | -| `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. | -| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. | -| `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10556) in GitLab 12.1). | -| `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | -| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5). In [GitLab 15.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/376760), you can also use the quick action when creating a new issue. | -| `/page <policy name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Start escalations for the incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79977) in GitLab 14.9). | -| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.0) | -| `/ready` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [ready status](merge_requests/drafts.md#mark-merge-requests-as-ready) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90361) in GitLab 15.1). | -| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | -| `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. | +| `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). +| `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. +| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. +| `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. +| `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. +| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5). In [GitLab 15.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/376760), you can also use the quick action when creating a new issue. +| `/page <policy name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Start escalations for the incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79977) in GitLab 14.9). +| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.0) +| `/ready` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [ready status](merge_requests/drafts.md#mark-merge-requests-as-ready) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90361) in GitLab 15.1). +| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. +| `/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](https://gitlab.com/gitlab-org/gitlab/-/issues/7330) in GitLab 12.0). | -| `/remove_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). | -| `/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` or `/remove_time_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. Alias `/remove_time_estimate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | -| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). | -| `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. | -| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10556) in GitLab 12.1). | -| `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. | -| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue. | -| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | -| `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Issue type must be `Incident`. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. | -| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | -| `/spend <time> [<date>]` or `/spend_time <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. For more information, see [Time tracking](time_tracking.md). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | -| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8041) in GitLab 12.7). | -| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. | -| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | -| `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | -| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | +| `/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. +| `/remove_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). +| `/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` or `/remove_time_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. Alias `/remove_time_estimate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. +| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). +| `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. +| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic. +| `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. +| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue. +| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. +| `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Issue type must be `Incident`. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. +| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. +| `/spend <time> [<date>]` or `/spend_time <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. For more information, see [Time tracking](time_tracking.md). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. +| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review. +| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. +| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. +| `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. +| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | `/timeline <timeline comment> \| <date(YYYY-MM-DD)> <time(HH:MM)>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a timeline event to this incident. For example, `/timeline DB load spiked \| 2022-09-07 09:30`. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368721) in GitLab 15.4). | -| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. | -| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) in GitLab 14.3 | -| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | -| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | +| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. +| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) in GitLab 14.3. +| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. +| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. -| `/unassign_reviewer me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove yourself as a reviewer. | -| `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. | -| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | -| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | -| `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. | -| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | -| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | -| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a Zoom meeting to this issue or incident. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) users on GitLab Premium can add a short description when [adding a Zoom link to an incident](../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident).| +| `/unassign_reviewer me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove yourself as a reviewer. +| `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. +| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. +| `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. +| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. +| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. +| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a Zoom meeting to this issue or incident. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) users on GitLab Premium can add a short description when [adding a Zoom link to an incident](../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident). +| `/blocks <issue1> <issue2>` | **{check-circle}** Yes | **{check-circle}** No | **{dotted-circle}** No | Mark the issue as blocking other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). +| `/blocked_by <issue1> <issue2>` | **{check-circle}** Yes | **{check-circle}** No | **{dotted-circle}** No | Mark the issue as blocked by other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). ## Work items -The following quick actions can be applied through the description field when editing work items. - -| Command | Task | Objective | Key Result | Action | -|:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | -| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | -| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | -| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | -| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | -| `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. [In GitLab 14.9 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/31200), mentioning a user at the start of a line creates a specific type of to-do item notification. | -| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign one or more users. | -| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign yourself. | -| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove specific assignees. | -| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove all assignees. | -| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Replace current assignees with those specified. | -| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | -| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | -| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | -| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | -| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | -| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Remove due date. | -| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk`. | -| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). | -| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. | -| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | +> Executing quick actions from comments [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391282) in GitLab 15.10. + +Work items in GitLab include [tasks](../tasks.md) and [OKRs](../okrs.md). +The following quick actions can be applied through the description field when editing or commenting on work items. + +| Command | Task | Objective | Key Result | Action +|:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| +| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. +| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. +| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. +| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. +| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. +| `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. [In GitLab 14.9 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/31200), mentioning a user at the start of a line creates a specific type of to-do item notification. +| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign one or more users. +| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign yourself. +| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove specific assignees. +| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove all assignees. +| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Replace current assignees with those specified. +| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. +| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. +| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. +| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Remove due date. +| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk`. +| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). +| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. +| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. +| `/type` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Converts work item to specified type. Available options for `<type>` include `Issue`, `Task`, `Objective` and `Key Result`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385227) in GitLab 16.0 [with a flag](../../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. ## Commit messages diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index dca34af41b4..d0c44b7e837 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -25,7 +25,7 @@ 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). + so you can compare and audit releases. This file is called [release evidence](release_evidence.md). When you create a release, or after, you can: @@ -45,8 +45,8 @@ To view a list of releases:  - On public projects, this number is visible to all users. - - On private projects, this number is visible to users with Reporter - [permissions](../../permissions.md#project-members-permissions) or higher. + - On private projects, this number is visible to users with at least the Reporter + [role](../../permissions.md#project-members-permissions). ### Sort releases @@ -63,7 +63,7 @@ You can create a release: - [In the Releases page](#create-a-release-in-the-releases-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. +You should create a release as one of the last steps in your CI/CD pipeline. ### Create a release in the Releases page @@ -80,15 +80,16 @@ To create a release in the Releases page: - 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 list, select a branch or commit SHA to use when + 1. From the **Create tag** popover, select a branch or commit SHA to use when creating the new tag. 1. Optional. In the **Set tag message** text box, enter a message to create an [annotated tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging#_annotated_tags). + 1. Select **Save**. 1. Optional. Enter additional information about the release, including: - [Title](release_fields.md#title). - [Milestones](#associate-milestones-with-a-release). - [Release notes](release_fields.md#release-notes-description). - - Whether or not to include the [Tag message](../../../topics/git/tags.md). + - Whether or not to include the [Tag message](../repository/tags/index.md). - [Asset links](release_fields.md#links). 1. Select **Create release**. @@ -179,7 +180,7 @@ release tag. When the `released_at` date and time has passed, the badge is autom You can create a release in the past using either the [Releases API](../../../api/releases/index.md#historical-releases) or the UI. When you set a past `released_at` date, an **Historical release** badge is displayed next to -the release tag. Due to being released in the past, [release evidence](#release-evidence) +the release tag. Due to being released in the past, [release evidence](release_evidence.md) is not available. ## Edit a release @@ -248,12 +249,12 @@ section, along with statistics about the issues in the milestones. Releases are also visible on the **Issues > Milestones** page, and when you select a milestone on this page. -Here is an example of milestones with no releases, one release, and two releases, respectively. +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 +A subgroup's project releases cannot be associated with a parent group's milestone. To learn more, read issue #328054, [Releases cannot be associated with a supergroup milestone](https://gitlab.com/gitlab-org/gitlab/-/issues/328054). @@ -283,7 +284,7 @@ Deploy freezes help reduce uncertainty and risk when automating deployments. A maintainer can set a deploy freeze window in the user interface or by using the [Freeze Periods API](../../../api/freeze_periods.md) to set a `freeze_start` and a `freeze_end`, which are defined as [crontab](https://crontab.guru/) entries. -If the job that's executing is within a freeze period, GitLab CI/CD creates an environment +If the job that's executing is in a freeze period, GitLab CI/CD creates an environment variable named `$CI_DEPLOY_FREEZE`. To prevent the deployment job from executing, create a `rules` entry in your @@ -316,141 +317,6 @@ complete overlapping period. For more information, see [Deployment safety](../../../ci/environments/deployment_safety.md). -## Release evidence - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. - -Each time a release is created, GitLab takes a snapshot of data that's related to it. -This data is saved in a JSON file and called *release evidence*. The feature -includes test artifacts and linked milestones to facilitate -internal processes, like external audits. - -To access the release evidence, on the Releases page, select the link to the JSON file that's listed -under the **Evidence collection** heading. - -You can also [use the API](../../../api/releases/index.md#collect-release-evidence) to -generate release evidence for an existing release. Because of this, each release -can have multiple release evidence snapshots. You can view the release evidence and -its details on the Releases page. - -When the issue tracker is disabled, release evidence [can't be downloaded](https://gitlab.com/gitlab-org/gitlab/-/issues/208397). - -Here is an example of a release evidence object: - -```json -{ - "release": { - "id": 5, - "tag_name": "v4.0", - "name": "New release", - "project": { - "id": 20, - "name": "Project name", - "created_at": "2019-04-14T11:12:13.940Z", - "description": "Project description" - }, - "created_at": "2019-06-28 13:23:40 UTC", - "description": "Release description", - "milestones": [ - { - "id": 11, - "title": "v4.0-rc1", - "state": "closed", - "due_date": "2019-05-12 12:00:00 UTC", - "created_at": "2019-04-17 15:45:12 UTC", - "issues": [ - { - "id": 82, - "title": "The top-right popup is broken", - "author_name": "John Doe", - "author_email": "john@doe.com", - "state": "closed", - "due_date": "2019-05-10 12:00:00 UTC" - }, - { - "id": 89, - "title": "The title of this page is misleading", - "author_name": "Jane Smith", - "author_email": "jane@smith.com", - "state": "closed", - "due_date": "nil" - } - ] - }, - { - "id": 12, - "title": "v4.0-rc2", - "state": "closed", - "due_date": "2019-05-30 18:30:00 UTC", - "created_at": "2019-04-17 15:45:12 UTC", - "issues": [] - } - ], - "report_artifacts": [ - { - "url":"https://gitlab.example.com/root/project-name/-/jobs/111/artifacts/download" - } - ] - } -} -``` - -### Collect release evidence **(PREMIUM SELF)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in GitLab 12.10. - -When a release is created, release evidence is automatically collected. To initiate evidence collection any other time, use an [API call](../../../api/releases/index.md#collect-release-evidence). You can collect release evidence multiple times for one release. - -Evidence collection snapshots are visible on the Releases page, along with the timestamp the evidence was collected. - -### Include report artifacts as release evidence **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32773) in GitLab 13.2. - -When you create a release, if [job artifacts](../../../ci/yaml/index.md#artifactsreports) are included in the last pipeline that ran, they are automatically included in the release as release evidence. - -Although job artifacts normally expire, artifacts included in release evidence do not expire. - -To enable job artifact collection you must specify both: - -1. [`artifacts:paths`](../../../ci/yaml/index.md#artifactspaths) -1. [`artifacts:reports`](../../../ci/yaml/index.md#artifactsreports) - -```yaml -ruby: - script: - - gem install bundler - - bundle install - - bundle exec rspec --format progress --format RspecJunitFormatter --out rspec.xml - artifacts: - paths: - - rspec.xml - reports: - junit: rspec.xml -``` - -If the pipeline ran successfully, when you create your release, the `rspec.xml` file is saved as -release evidence. - -If you [schedule release evidence collection](#schedule-release-evidence-collection), -some artifacts may already be expired by the time of evidence collection. To avoid this you can use -the [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) -keyword. For more information, see [issue 222351](https://gitlab.com/gitlab-org/gitlab/-/issues/222351). - -### Schedule release evidence collection - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23697) in GitLab 12.8. - -In the API: - -- If you specify a future `released_at` date, the release becomes an **Upcoming release** - and the evidence is collected on the date of the release. You cannot collect - release evidence before then. -- If you specify a past `released_at` date, the release becomes an **Historical - release** and no evidence is collected. -- If you do not specify a `released_at` date, release evidence is collected on the - date the release is created. - ## Release permissions > Fixes to the permission model for create, update and delete actions [were introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327505) in GitLab 14.1. @@ -464,14 +330,15 @@ In the API: - Users with the Guest role have read and download access to the project releases. This includes associated Git-tag-names, release description, author information of the releases. - However, other repository-related information, such as [source code](release_fields.md#source-code), [release evidence](#release-evidence) are redacted. + However, other repository-related information, such as [source code](release_fields.md#source-code) and + [release evidence](release_evidence.md) are redacted. ### Publish releases without giving access to source code > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216485) in GitLab 15.6. Releases can be made accessible to non-project members while keeping repository-related information such as -[source code](release_fields.md#source-code) and [release evidence](#release-evidence) private. This is useful for +[source code](release_fields.md#source-code) and [release evidence](release_evidence.md) private. Use this for projects that use releases as a way to give access to new versions of software but do not want the source code to be public. @@ -527,4 +394,4 @@ See [the release permissions](#release-permissions) for more information. ### Note about storage -Note that the feature is built on top of Git tags, so virtually no extra data is needed besides to create the release itself. Additional assets and the release evidence that is automatically generated consume storage. +This feature is built on top of Git tags, so virtually no extra data is needed besides to create the release itself. Additional assets and the release evidence that is automatically generated consume storage. diff --git a/doc/user/project/releases/release_cicd_examples.md b/doc/user/project/releases/release_cicd_examples.md index 1ec82d6702e..7b5e808641c 100644 --- a/doc/user/project/releases/release_cicd_examples.md +++ b/doc/user/project/releases/release_cicd_examples.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index 5af19c7cced..bd3cfd26f1b 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/releases/release_evidence.md b/doc/user/project/releases/release_evidence.md new file mode 100644 index 00000000000..3269bf8f44b --- /dev/null +++ b/doc/user/project/releases/release_evidence.md @@ -0,0 +1,140 @@ +--- +stage: Govern +group: Compliance +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Release evidence **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. + +Each time a release is created, GitLab takes a snapshot of data that's related to it. +This data is saved in a JSON file and called *release evidence*. The feature +includes test artifacts and linked milestones to facilitate +internal processes, like external audits. + +To access the release evidence, on the Releases page, select the link to the JSON file that's listed +under the **Evidence collection** heading. + +You can also [use the API](../../../api/releases/index.md#collect-release-evidence) to +generate release evidence for an existing release. Because of this, each release +can have multiple release evidence snapshots. You can view the release evidence and +its details on the Releases page. + +When the issue tracker is disabled, release evidence [can't be downloaded](https://gitlab.com/gitlab-org/gitlab/-/issues/208397). + +Here is an example of a release evidence object: + +```json +{ + "release": { + "id": 5, + "tag_name": "v4.0", + "name": "New release", + "project": { + "id": 20, + "name": "Project name", + "created_at": "2019-04-14T11:12:13.940Z", + "description": "Project description" + }, + "created_at": "2019-06-28 13:23:40 UTC", + "description": "Release description", + "milestones": [ + { + "id": 11, + "title": "v4.0-rc1", + "state": "closed", + "due_date": "2019-05-12 12:00:00 UTC", + "created_at": "2019-04-17 15:45:12 UTC", + "issues": [ + { + "id": 82, + "title": "The top-right popup is broken", + "author_name": "John Doe", + "author_email": "john@doe.com", + "state": "closed", + "due_date": "2019-05-10 12:00:00 UTC" + }, + { + "id": 89, + "title": "The title of this page is misleading", + "author_name": "Jane Smith", + "author_email": "jane@smith.com", + "state": "closed", + "due_date": "nil" + } + ] + }, + { + "id": 12, + "title": "v4.0-rc2", + "state": "closed", + "due_date": "2019-05-30 18:30:00 UTC", + "created_at": "2019-04-17 15:45:12 UTC", + "issues": [] + } + ], + "report_artifacts": [ + { + "url":"https://gitlab.example.com/root/project-name/-/jobs/111/artifacts/download" + } + ] + } +} +``` + +## Collect release evidence **(PREMIUM SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in GitLab 12.10. + +When a release is created, release evidence is automatically collected. To initiate evidence collection any other time, use an [API call](../../../api/releases/index.md#collect-release-evidence). You can collect release evidence multiple times for one release. + +Evidence collection snapshots are visible on the Releases page, along with the timestamp the evidence was collected. + +## Include report artifacts as release evidence **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32773) in GitLab 13.2. + +When you create a release, if [job artifacts](../../../ci/yaml/index.md#artifactsreports) are included in the last pipeline that ran, they are automatically included in the release as release evidence. + +Although job artifacts normally expire, artifacts included in release evidence do not expire. + +To enable job artifact collection you must specify both: + +1. [`artifacts:paths`](../../../ci/yaml/index.md#artifactspaths) +1. [`artifacts:reports`](../../../ci/yaml/index.md#artifactsreports) + +```yaml +ruby: + script: + - gem install bundler + - bundle install + - bundle exec rspec --format progress --format RspecJunitFormatter --out rspec.xml + artifacts: + paths: + - rspec.xml + reports: + junit: rspec.xml +``` + +If the pipeline ran successfully, when you create your release, the `rspec.xml` file is saved as +release evidence. + +If you [schedule release evidence collection](#schedule-release-evidence-collection), +some artifacts may already be expired by the time of evidence collection. To avoid this you can use +the [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) +keyword. For more information, see [issue 222351](https://gitlab.com/gitlab-org/gitlab/-/issues/222351). + +## Schedule release evidence collection + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23697) in GitLab 12.8. + +In the API: + +- If you specify a future `released_at` date, the release becomes an **Upcoming release** + and the evidence is collected on the date of the release. You cannot collect + release evidence before then. +- If you specify a past `released_at` date, the release becomes an **Historical + release** and no evidence is collected. +- If you do not specify a `released_at` date, release evidence is collected on the + date the release is created. diff --git a/doc/user/project/releases/release_fields.md b/doc/user/project/releases/release_fields.md index 120bbe32a63..d26ca87e384 100644 --- a/doc/user/project/releases/release_fields.md +++ b/doc/user/project/releases/release_fields.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -90,6 +90,8 @@ By default, GitLab fetches the release using `released_at` time. The use of the #### Permanent links to release assets +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375489) in GitLab 15.9, links for private releases can be accessed using a Personal Access Token. + The assets associated with a release are accessible through a permanent URL. GitLab always redirects this URL to the actual asset location, so even if the assets move to a different location, you can continue @@ -121,6 +123,14 @@ https://gitlab.com/gitlab-org/gitlab-runner/-/releases/v11.9.0-rc2/downloads/bin The physical location of the asset can change at any time and the direct link remains unchanged. +If the release is private, you need to provide a Personal Access Token with either `api` or `read_api` scopes using +a `private_token` query parameter or a `HTTP_PRIVATE_TOKEN` header when making the request. For example: + +```shell +curl --location --output filename "https://gitlab.example.com/my-group/my-project/-/releases/:release/downloads/:filepath?private_token=<your_access_token>" +curl --location --output filename --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/my-group/my-project/-/releases/:release/downloads/:filepath" +``` + #### Permanent links to latest release assets > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16821) in GitLab 14.9. @@ -245,7 +255,7 @@ release: ``` NOTE: -Directly attaching [job artifacts](../../../ci/pipelines/job_artifacts.md) +Directly attaching [job artifacts](../../../ci/jobs/job_artifacts.md) 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. diff --git a/doc/user/project/remote_development/connect_machine.md b/doc/user/project/remote_development/connect_machine.md new file mode 100644 index 00000000000..f981918c0ea --- /dev/null +++ b/doc/user/project/remote_development/connect_machine.md @@ -0,0 +1,109 @@ +--- +stage: Create +group: IDE +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Tutorial: Connect a remote machine to the Web IDE **(FREE)** + +This tutorial shows you how to: + +- Create a development environment outside of GitLab. +- Connect a remote machine to the [Web IDE](../web_ide/index.md). + +To connect a remote machine to the Web IDE, you must: + +1. [Generate Let's Encrypt certificates](#generate-lets-encrypt-certificates). +1. [Connect a development environment to the Web IDE](#connect-a-development-environment-to-the-web-ide). + +## Prerequisites + +- A remote virtual machine with root access +- A domain address resolving to that machine +- Docker installation + +## Generate Let's Encrypt certificates + +To generate Let's Encrypt certificates: + +1. Create an `A` record to point a domain to your remote machine (for example, from `example.remote.gitlab.dev` to `1.2.3.4`). +1. Install [Certbot](https://certbot.eff.org/) to enable HTTPS: + + ```shell + sudo apt-get update + sudo apt-get install certbot + ``` + +1. Generate the certificates: + + ```shell + export EMAIL="YOUR_EMAIL@example.com" + export DOMAIN="example.remote.gitlab.dev" + + certbot -d "${DOMAIN}" \ + -m "${EMAIL}" \ + --config-dir ~/.certbot/config \ + --logs-dir ~/.certbot/logs \ + --work-dir ~/.certbot/work \ + --manual \ + --preferred-challenges dns certonly + ``` + +Now that you've generated the certificates, it's time to create and connect a development environment. + +## Connect a development environment to the Web IDE + +To connect a development environment to the Web IDE: + +1. Create a development environment: + + ```shell + export CERTS_DIR="/home/ubuntu/.certbot/config/live/${DOMAIN}" + export PROJECTS_DIR="/home/ubuntu" + + docker run -d \ + --name my-environment \ + -p 3443:3443 \ + -v "${CERTS_DIR}/fullchain.pem:/gitlab-rd-web-ide/certs/fullchain.pem" \ + -v "${CERTS_DIR}/privkey.pem:/gitlab-rd-web-ide/certs/privkey.pem" \ + -v "${PROJECTS_DIR}:/projects" \ + registry.gitlab.com/gitlab-org/remote-development/gitlab-rd-web-ide-docker:0.2-alpha \ + --log-level warn --domain "${DOMAIN}" --ignore-version-mismatch + ``` + + The new development environment starts automatically. + +1. Fetch a token: + + ```shell + docker exec my-environment cat TOKEN + ``` + +1. [Configure a remote connection](#configure-a-remote-connection). + +### Configure a remote connection + +To configure a remote connection from the Web IDE: + +1. Open the Web IDE. +1. On the menu bar, select **View > Terminal** or press <kbd>Control</kbd>+<kbd>`</kbd>. +1. In the terminal panel, select **Configure a remote connection**. +1. Enter the URL for the remote host including the port (for example, `yourdomain.com:3443`). +1. Enter the project path. +1. Enter the token you've fetched. + +Alternatively, you can pass the parameters from a URL and connect directly to the Web IDE: + +1. Run this command: + + ```shell + echo "https://gitlab-org.gitlab.io/gitlab-web-ide?remoteHost=${DOMAIN}:3443&hostPath=/projects" + ``` + +1. Go to that URL and enter the token you've fetched. + +You've done it! Your development environment now runs as a remote host that's connected to the Web IDE. + +## Related topics + +- [Manage a development environment](index.md#manage-a-development-environment) diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md index 1abcca547db..d4156de2ebe 100644 --- a/doc/user/project/remote_development/index.md +++ b/doc/user/project/remote_development/index.md @@ -1,91 +1,59 @@ --- stage: Create -group: Editor +group: IDE info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Remote Development **(FREE)** +# Remote development (Beta) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115741) in GitLab 15.11. 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 `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. WARNING: -This feature is in [Alpha](../../../policy/alpha-beta-support.md#alpha-features) and subject to change without notice. +This feature is in [Beta](../../../policy/alpha-beta-support.md#beta) and subject to change without notice. -DISCLAIMER: -This page contains information related to upcoming products, features, and functionality. -It is important to note that the information presented is for informational purposes only. -Please do not rely on this information for purchasing or planning purposes. -As with all projects, the items mentioned on this page are subject to change or delay. -The development, release, and timing of any products, features, or functionality remain at the -sole discretion of GitLab Inc. +You can use remote development to write and compile code hosted on GitLab. With remote development, you can: -You can use the [Web IDE](../web_ide/index.md) to commit changes to a project directly from your web browser without installing any dependencies or cloning any repositories. The Web IDE, however, lacks a native runtime environment on which you would compile code, run tests, or generate real-time feedback in the IDE. For a more complete IDE experience, you can pair the [Web IDE Beta](../web_ide_beta/index.md) with a Remote Development environment that has been properly configured to run as a host. +- Create a secure development environment in the cloud. +- Connect to that environment from your local machine through a web browser or client-based solution. -## Connect a remote machine to the Web IDE +## Web IDE as a frontend -Prerequisites: +You can use the [Web IDE](../web_ide/index.md) to make, commit, and push changes to a project directly from your web browser. +This way, you can update any project without having to install any dependencies or clone any repositories locally. -- A remote virtual machine with root access -- A domain address resolving to that machine -- Docker installation +The Web IDE, however, lacks a native runtime environment where you could compile code, run tests, or generate real-time feedback. +With remote development, you can use: -To connect a remote machine to the Web IDE, you must: +- The Web IDE as a frontend +- A separate machine as a backend runtime environment -1. [Generate Let's Encrypt certificates](#generate-lets-encrypt-certificates). -1. [Connect a development environment to the Web IDE](#connect-a-development-environment-to-the-web-ide). +For a complete IDE experience, connect the Web IDE to a development environment configured to run as a remote host. You can create this environment [inside](../../workspace/index.md) or [outside](connect_machine.md) of GitLab. -### Generate Let's Encrypt certificates +## Workspace -To generate Let's Encrypt certificates: +A [workspace](../../workspace/index.md) is a virtual sandbox environment for your code in GitLab that includes: -1. [Point a domain to your remote machine](#point-a-domain-to-your-remote-machine). -1. [Install Certbot](#install-certbot). -1. [Generate the certificates](#generate-the-certificates). +- A runtime environment +- Dependencies +- Configuration files -#### Point a domain to your remote machine +You can create a workspace from scratch or from a template that you can also customize. -To point a domain to your remote machine, create an `A` record from `example.remote.gitlab.dev` to `1.2.3.4`. +When you configure and connect a workspace to the [Web IDE](../web_ide/index.md), you can: -#### Install Certbot +- Edit files directly from the Web IDE and commit and push changes to GitLab. +- Use the Web IDE to run tests, debug code, and view real-time feedback. -[Certbot](https://certbot.eff.org/) is a free and open-source software tool that automatically uses Let's Encrypt certificates on manually administered websites to enable HTTPS. +## Manage a development environment -To install Certbot, run the following command: +### Create a development environment -```shell -sudo apt-get update -sudo apt-get install certbot -``` - -#### Generate the certificates - -```shell -export EMAIL="YOUR_EMAIL@example.com" -export DOMAIN="example.remote.gitlab.dev" - -certbot -d "${DOMAIN}" \ - -m "${EMAIL}" \ - --config-dir ~/.certbot/config \ - --logs-dir ~/.certbot/logs \ - --work-dir ~/.certbot/work \ - --manual \ - --preferred-challenges dns certonly -``` - -### Connect a development environment to the Web IDE - -To connect a development environment to the Web IDE: - -1. [Create a development environment](#manage-a-development-environment). -1. [Fetch a token](#fetch-a-token). -1. [Configure a remote connection](#configure-a-remote-connection). - -#### Manage a development environment - -**Create a development environment** +To create a development environment, run this command: ```shell export CERTS_DIR="/home/ubuntu/.certbot/config/live/${DOMAIN}" @@ -97,64 +65,37 @@ docker run -d \ -v "${CERTS_DIR}/fullchain.pem:/gitlab-rd-web-ide/certs/fullchain.pem" \ -v "${CERTS_DIR}/privkey.pem:/gitlab-rd-web-ide/certs/privkey.pem" \ -v "${PROJECTS_DIR}:/projects" \ - registry.gitlab.com/gitlab-com/create-stage/editor-poc/remote-development/gitlab-rd-web-ide-docker:0.1-alpha \ + registry.gitlab.com/gitlab-org/remote-development/gitlab-rd-web-ide-docker:0.2-alpha \ --log-level warn --domain "${DOMAIN}" --ignore-version-mismatch ``` The new development environment starts automatically. -**Stop a development environment** +### Stop a development environment + +To stop a running development environment, run this command: ```shell docker container stop my-environment ``` -**Start a development environment** +### Start a development environment + +To start a stopped development environment, run this command: ```shell docker container start my-environment ``` -The token changes every time you restart the development environment. +The token changes every time you start the development environment. -**Remove a development environment** +### Remove a development environment To remove a development environment: -1. Stop the development environment. -1. Run the following command: +1. [Stop the development environment](#stop-a-development-environment). +1. Run this command: ```shell docker container rm my-environment ``` - -#### Fetch a token - -```shell -docker exec my-environment cat TOKEN -``` - -#### Configure a remote connection - -To configure a remote connection from the Web IDE: - -1. Open the Web IDE. -1. In the Menu Bar, select **View > Terminal** or press <kbd>Control</kbd>+<kbd>`</kbd>. -1. In the terminal panel, select **Configure a remote connection**. -1. Enter the URL for the remote host including the port (for example, `yourdomain.com:3443`). -1. Enter the project path. -1. Enter the [token you fetched](#fetch-a-token). - -Alternatively, you can pass the parameters from a URL and connect directly to the Web IDE: - -1. Run the following command: - - ```shell - echo "https://gitlab-org.gitlab.io/gitlab-web-ide?remoteHost=${DOMAIN}:3443&hostPath=/projects" - ``` - -1. Go to that URL and enter the [token you fetched](#fetch-a-token). - -## Related topics - -- [Web IDE Beta](../web_ide_beta/index.md) diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index b33dc4450a9..e58cc0bf6a4 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -134,7 +134,7 @@ groups and subgroups can override this instance-wide setting for their projects. Instance-level protections for default branches can be overridden on a per-group basis by the group's owner. In -[GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can +[GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), GitLab administrators can disable this privilege for group owners, enforcing the instance-level protection rule: 1. On the top bar, select **Main menu > Admin**. @@ -153,7 +153,7 @@ GitLab administrators can still update the default branch protection of a group. Instance-level protections for [default branch](#default-branch) can be overridden on a per-group basis by the group's owner. In -[GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can +[GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), GitLab administrators can [enforce protection of initial default branches](#prevent-overrides-of-default-branch-protection) which locks this setting for group owners. diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_12.png b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_12.png Binary files differdeleted file mode 100644 index a1cf9f10122..00000000000 --- a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_12.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/compare_branches_v13_12.png b/doc/user/project/repository/branches/img/compare_branches_v13_12.png Binary files differdeleted file mode 100644 index 29627406729..00000000000 --- a/doc/user/project/repository/branches/img/compare_branches_v13_12.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/repository_filter_search_box_v13_12.png b/doc/user/project/repository/branches/img/repository_filter_search_box_v13_12.png Binary files differdeleted file mode 100644 index 230abf0d875..00000000000 --- a/doc/user/project/repository/branches/img/repository_filter_search_box_v13_12.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/swap_revisions_after_v13_12.png b/doc/user/project/repository/branches/img/swap_revisions_after_v13_12.png Binary files differdeleted file mode 100644 index 7eb10d10938..00000000000 --- a/doc/user/project/repository/branches/img/swap_revisions_after_v13_12.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/swap_revisions_before_v13_12.png b/doc/user/project/repository/branches/img/swap_revisions_before_v13_12.png Binary files differdeleted file mode 100644 index f92c4279871..00000000000 --- a/doc/user/project/repository/branches/img/swap_revisions_before_v13_12.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/view_branch_protections_v15_10.png b/doc/user/project/repository/branches/img/view_branch_protections_v15_10.png Binary files differnew file mode 100644 index 00000000000..8472015c21b --- /dev/null +++ b/doc/user/project/repository/branches/img/view_branch_protections_v15_10.png diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 60504b94502..7c09ce5c580 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -6,142 +6,260 @@ info: "To determine the technical writer assigned to the Stage/Group associated # Branches **(FREE)** -A branch is a version of a project's working tree. You create a branch for each -set of related changes you make. This keeps each set of changes separate from -each other, allowing changes to be made in parallel, without affecting each -other. +Branches are versions of a project's working tree. When you create a new +[project](../../index.md), GitLab creates a [default branch](default.md) (which +cannot be deleted) for your repository. Default branch settings can be configured +at the project, subgroup, group, or instance level. -After pushing your changes to a new branch, you can: +As your project grows, your team [creates](../web_editor.md#create-a-branch) more +branches, preferably by following [branch naming patterns](#prefix-branch-names-with-issue-numbers). +Each branch represents a set of changes, which allows development work to be done +in parallel. Development work in one branch does not affect another branch. -- Create a [merge request](../../merge_requests/index.md). You can streamline this process - by following [branch naming patterns](#naming). -- Perform inline code review. -- [Discuss](../../../discussions/index.md) your implementation with your team. -- Preview changes submitted to a new branch with [Review Apps](../../../../ci/review_apps/index.md). +Branches are the foundation of development in a project: -You can also request [approval](../../merge_requests/approvals/index.md) -from your managers. +1. To get started, create a branch and add commits to it. +1. When the work is ready for review, create a [merge request](../../merge_requests/index.md) to propose + merging the changes in your branch. To streamline this process, you should follow + [branch naming patterns](#prefix-branch-names-with-issue-numbers). +1. Preview changes in a branch with a [review app](../../../../ci/review_apps/index.md). +1. After the contents of your branch are merged, [delete the merged branch](#delete-merged-branches). -For more information on managing branches using the GitLab UI, see: +## Create branch -- [Default branches](default.md): When you create a new [project](../../index.md), GitLab creates a - default branch for the repository. You can change this setting at the project, - subgroup, group, or instance level. -- [Create a branch](../web_editor.md#create-a-branch) -- [Protected branches](../../protected_branches.md#protected-branches) -- [Delete merged branches](#delete-merged-branches) -- [Branch filter search box](#branch-filter-search-box) +To create a new branch from the GitLab UI: -You can also manage branches using the -[command line](../../../../gitlab-basics/start-using-git.md#create-a-branch). +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Branches**. +1. On the top right, select **New branch**. +1. Enter a **Branch name**. +1. In **Create from**, select the base of your branch: an existing branch, an existing + tag, or a commit SHA. +1. Select **Create branch**. -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>Watch the video [GitLab Flow](https://www.youtube.com/watch?v=InKNIvky2KE). +### In a blank project -See also: +A [blank project](../../index.md#create-a-blank-project) does not contain a branch, but +you can add one. -- [Branches API](../../../../api/branches.md), for information on operating on repository branches using the GitLab API. -- [GitLab Flow](../../../../topics/gitlab_flow.md) documentation. -- [Getting started with Git](../../../../topics/git/index.md) and GitLab. +Prerequisites: -## Naming +- You must have at least the Developer role in the project. +- Unless you have the Maintainer or Owner roles, the + [default branch protection](../../../group/manage.md#change-the-default-branch-protection-of-a-group) + must be set to `Partially protected` or `Not protected` for you to push a commit + to the default branch. -Prefix a branch name with an issue number to streamline merge request creation. -When you create a merge request for a branch with a name beginning with an issue -number, GitLab: +To add a [default branch](default.md) to an empty project: -- Marks the issue as related. If your project is configured with a - [default closing pattern](../../issues/managing_issues.md#default-closing-pattern), - merging this merge request [also closes](../../issues/managing_issues.md#closing-issues-automatically) - the related issue. -- Copies label and milestone metadata from the issue. +1. On the top bar, select **Main menu > Projects** and find your project. +1. Scroll to **The repository for this project is empty** and select the type of + file you want to add. +1. In the Web IDE, make any desired changes to this file, then select **Create commit**. +1. Enter a commit message, and select **Commit**. -## Compare +GitLab creates a default branch and adds your file to it. -To compare branches in a repository: +### From an issue -1. Navigate to your project's repository. -1. Select **Repository > Compare** in the sidebar. -1. Select the target repository to compare with the [repository filter search box](#repository-filter-search-box). -1. Select branches to compare using the [branch filter search box](#branch-filter-search-box). -1. Select **Compare** to view the changes inline: +When viewing an issue, you can create an associated branch directly from that page. -  +Prerequisites: -## Delete merged branches +- You must have at least the Developer role in the project. - +To create a branch from an issue: -This feature allows merged branches to be deleted in bulk. Only branches that -have been merged into the project's default branch and -[are not protected](../../protected_branches.md) are deleted as part of -this operation. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues** (**{issues}**) and find your issue. +1. Below the issue description, find the **Create merge request** dropdown list, and select + **{chevron-down}** to display the dropdown list. +1. Select **Create branch**. A default **Branch name** is provided, based on the + [default pattern](#configure-default-pattern-for-branch-names-from-issues) for + this project. If desired, enter a different **Branch name**. +1. Select **Create branch** to create the branch based on your project's + [default branch](default.md). -It's particularly useful to clean up old branches that were not deleted -automatically when a merge request was merged. +## Manage and protect branches + +GitLab provides you multiple methods to protect individual branches. These methods +ensure your branches receive oversight and quality checks from their creation to their deletion: -## Repository filter search box +- The [default branch](default.md) in your project receives extra protection. +- Configure [protected branches](../../protected_branches.md#protected-branches) + to restrict who can commit to a branch, merge other branches into it, or merge + the branch itself into another branch. +- Configure [approval rules](../../merge_requests/approvals/rules.md) to set review + requirements, including [security-related approvals](../../merge_requests/approvals/rules.md#security-approvals), before a branch can merge. +- Integrate with third-party [status checks](../../merge_requests/status_checks.md) + to ensure your branch contents meet your standards of quality. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52967) in GitLab 13.10. +You can manage your branches: -This feature allows you to search and select a repository quickly when [comparing branches](#compare). +- With the GitLab user interface. +- With the [command line](../../../../gitlab-basics/start-using-git.md#create-a-branch). +- With the [Branches API](../../../../api/branches.md). - +### View all branches -Search results appear in the following order: +To view and manage your branches in the GitLab user interface: -- Repositories with names exactly matching the search terms. -- Other repositories with names that include search terms, sorted alphabetically. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Branches**. -## Branch filter search box +On this page, you can: - +- See all branches, active branches, or stale branches. +- Create new branches. +- [Compare branches](#compare-branches). +- Delete merged branches. -This feature allows you to search and select branches quickly. Search results appear in the following order: +### View branches with configured protections -- Branches with names that matched search terms exactly. -- Other branches with names that include search terms, sorted alphabetically. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 15.1 with a flag named `branch_rules`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/363170) in GitLab 15.10. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/363170) in GitLab 15.11 -Sometimes when you have hundreds of branches you may want a more flexible matching pattern. In such cases you can use the following operators: +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../feature_flags.md) named `branch_rules`. +On GitLab.com, this feature is available. -- `^` matches beginning of branch name, for example `^feat` would match `feat/user-authentication` -- `$` matches end of branch name, for example `widget$` would match `feat/search-box-widget` -- `*` wildcard matcher, for example `branch*cache*` would match `fix/branch-search-cache-expiration` +Branches in your repository can be [protected](../../protected_branches.md) in multiple ways. You can: -These operators can be mixed, for example `^chore/*migration$` would match `chore/user-data-migration` +- Limit who can push to the branch. +- Limit who can merge the branch. +- Require approval of all changes. +- Require external tests to pass. -## Swap revisions +The **Branch rules overview** page shows all branches with any configured protections, +and their protection methods: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60491) in GitLab 13.12. + - +Prerequisites: -The Swap revisions feature allows you to swap the Source and Target revisions. When the Swap revisions button is selected, the selected revisions for Source and Target is swapped. +- You must have at least the Maintainer role in the project. - +To view the **Branch rules overview** list: -## View branches with configured protections **(FREE SELF)** +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Branch Rules** to view all branches with protections. + - To add protections to a new branch: + 1. Select **Add branch rule**. + 1. Select **Create protected branch**. + - To view more information about protections on an existing branch: + 1. Identify the branch you want more information about. + 1. Select **Details** to see information about its: + - [Branch protections](../../protected_branches.md). + - [Approval rules](../../merge_requests/approvals/rules.md). + - [Status checks](../../merge_requests/status_checks.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 15.1 with a flag named `branch_rules`. Disabled by default. +## Name your branch -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../feature_flags.md) named `branch_rules`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +Git enforces [branch name rules](https://git-scm.com/docs/git-check-ref-format) +to help ensure branch names remain compatible with other tools. GitLab +adds extra requirements for branch names, and provides benefits for well-structured branch names. -Branches in your repository can be [protected](../../protected_branches.md) by limiting -who can push to a branch, require approval for those pushed changes, or merge those changes. -To help you track the protections for all branches, the **Branch rules overview** -page shows your branches with their configured rules. +GitLab enforces these additional rules on all branches: -To view the **Branch rules overview** list: +- No spaces are allowed in branch names. +- Branch names with 40 hexadecimal characters are prohibited, because they are similar to Git commit hashes. + +Common software packages, like Docker, may enforce +[additional branch naming restrictions](../../../../administration/packages/container_registry.md#docker-connection-error). + +For best compatibility with other software packages, use only numbers, hyphens (`-`), +underscores (`_`), and lower-case letters from the ASCII standard table. You +can use forward slashes (`/`) and emoji in branch names, but compatibility with other +software packages cannot be guaranteed. + +Branch names with specific formatting offer extra benefits: + +- Streamline your merge request workflow by + [prefixing branch names with issue numbers](#prefix-branch-names-with-issue-numbers). +- Automate [branch protections](../../protected_branches.md) based on branch name. +- Test branch names with [push rules](../push_rules.md) before branches are pushed up to GitLab. +- Define which [CI/CD jobs](../../../../ci/jobs/index.md) to run on merge requests. + +### Configure default pattern for branch names from issues + +By default, GitLab uses the pattern `%{id}-%{title}` when creating a branch from +an issue, but you can change this pattern. + +Prerequisites: + +- You must have at least the Maintainer role for the project. + +To change the default pattern for branches created from issues: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. -1. Expand **Branch Rules** to view all branches with protections. -1. Select **Details** next to your desired branch to show information about its: - - [Branch protections](../../protected_branches.md). - - [Approval rules](../../merge_requests/approvals/rules.md). - - [Status checks](../../merge_requests/status_checks.md). +1. On the left sidebar, select **Settings > Repository** and expand **Branch defaults**. +1. Scroll to **Branch name template** and enter a value. The field supports these variables: + - `%{id}`: The numeric ID of the issue. + - `%{title}`: The title of the issue, modified to use only characters acceptable in Git branch names. +1. Select **Save changes**. + +### Prefix branch names with issue numbers + +To streamline the creation of merge requests, start your branch name with an +issue number. GitLab uses the issue number to import data into the merge request: + +- The issue is marked as related to the merge request. The issue and merge request + display links to each other. +- The branch is connected to the issue. +- If your project is configured with a + [default closing pattern](../../issues/managing_issues.md#default-closing-pattern), + merging the merge request [also closes](../../issues/managing_issues.md#closing-issues-automatically) + the related issue. +- Issue milestone and labels are copied to the merge request. + +## Compare branches + +> - Repository filter search box [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52967) in GitLab 13.10. +> - Revision swapping [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60491) in GitLab 13.12. + +The default compare mode uses the `git diff from...to` method, instead of the +`git diff from to` method, to compare branches. The `git diff from...to` method +provides a more human-readable diff, because it does not include unrelated changes +made to the target branch after the source branch was created. + +NOTE: +The `git diff from...to` method shows all changes from a cherry-picked commit as +new changes. It uses the merge base, not the actual commit content, to compare branches. + +To compare branches in a repository: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Compare revisions**. +1. Select the **Source** branch to search for your desired branch. Exact matches are + shown first. You can refine your search with operators: + - `^` matches the beginning of the branch name: `^feat` matches `feat/user-authentication`. + - `$` matches the end of the branch name: `widget$` matches `feat/search-box-widget`. + - `*` matches using a wildcard: `branch*cache*` matches `fix/branch-search-cache-expiration`. + - You can combine operators: `^chore/*migration$` matches `chore/user-data-migration`. +1. Select the **Target** repository and branch. Exact matches are shown first. +1. Select **Compare** to show the list of commits, and changed files. To reverse + the **Source** and **Target**, select **Swap revisions**. + +## Delete merged branches + + + +This feature allows merged branches to be deleted in bulk. Only branches that +have been merged into the project's default branch and +[are not protected](../../protected_branches.md) are deleted as part of +this operation. + +It's particularly useful to clean up old branches that were not deleted +automatically when a merge request was merged. + +## Related topics + +- [Protected branches](../../protected_branches.md) +- [Branches API](../../../../api/branches.md) +- [Protected Branches API](../../../../api/protected_branches.md) +- [Getting started with Git](../../../../topics/git/index.md) ## Troubleshooting diff --git a/doc/user/project/repository/code_suggestions.md b/doc/user/project/repository/code_suggestions.md new file mode 100644 index 00000000000..5de55db5ad4 --- /dev/null +++ b/doc/user/project/repository/code_suggestions.md @@ -0,0 +1,182 @@ +--- +stage: ModelOps +group: AI Assisted +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: index, reference +--- + +# Code Suggestions (Beta) **(FREE SAAS)** + +> - [Introduced](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#code-suggestions-available-in-closed-beta) in GitLab 15.9 as [Beta](/ee/policy/alpha-beta-support.md#beta) for early access Ultimate customers. +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/408104) as opt-in with GitLab 15.11 as [Beta](/ee/policy/alpha-beta-support.md#beta). +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/408158) from GitLab Ultimate to GitLab Premium in 16.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/410801) from GitLab Premium to GitLab Free in 16.0. + +WARNING: +This feature is in [Beta](/ee/policy/alpha-beta-support.md#beta). +Code Suggestions use generative AI to suggest code while you're developing. +Due to high demand, this feature will have unscheduled downtime and code suggestions in VS Code may be delayed. +Code Suggestions may produce [low-quality or incomplete suggestions](#model-accuracy-and-quality). +Beta users should read about the [known limitations](#known-limitations). We look forward to hearing your feedback. + +Use Code Suggestions to write code more efficiently by viewing code suggestions +as you type. Depending on the cursor position, the extension either: + +- Provides entire code snippets, like generating functions. +- Completes the current line. + +To accept a suggestion, press <kbd>Tab</kbd>. + +Code Suggestions are available in Visual Studio Code when you have the GitLab Workflow extension installed. + +## Supported languages + +Code Suggestions may produce [low-quality or incomplete suggestions](#model-accuracy-and-quality). The best results from Code Suggestions are expected for these languages: + +- C/C++ +- C# +- Go +- Java +- JavaScript +- Python +- PHP +- Ruby +- Rust +- Scala +- TypeScript + +Suggestions may be mixed for other languages. Using natural language code comments to request completions may also not function as expected. + +GitLab is continuously improving the model and expects to support an additional seven languages soon, as well as natural language code comments. + +Usage of Code Suggestions is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). Learn about [data usage when using Code Suggestions](#code-suggestions-data-usage). + +## Enable Code Suggestions in VS Code + +Prerequisites: + +- Your group owner must enable the [group level code suggestions setting](../../group/manage.md#group-code-suggestions). +- You must have [a personal access token](../../profile/personal_access_tokens.md#create-a-personal-access-token) with the `read_api` and `read_user` scopes. + +To enable Code Suggestions in VS Code: + +1. Download and configure the + [GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) + for Visual Studio Code. +1. In **GitLab: Add Account to VS Code on Mac**, add your GitLab work account to the VS Code extension: + - In macOS, press <kbd>Shift</kbd> + <kbd>Command</kbd> + <kbd>P</kbd>. + - In Windows, press <kbd>Shift</kbd> + <kbd>Control</kbd> + <kbd>P</kbd>. +1. Provide your GitLab instance URL. A default is provided. +1. Provide your personal access token. +1. After your GitLab account connects successfully, in the left sidebar, select **Extensions**. +1. Find the **GitLab workflow** extension, select **Settings** (**{settings}**), and select **Extension Settings**. +1. Enable **GitLab > AI Assisted Code Suggestions**. + +Start typing and receive suggestions for your GitLab projects. + +<div class="video-fallback"> + See an end-to-end demo: <a href="https://www.youtube.com/watch?v=WnxBYxN2-p4">Get started with GitLab Code Suggestions in VS Code</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/WnxBYxN2-p4" frameborder="0" allowfullscreen> </iframe> +</figure> + +## Code Suggestions data usage + +Code Suggestions is a generative artificial intelligence (AI) model hosted on GitLab.com. + +Your personal access token enables a secure API connection to GitLab.com. +This API connection securely transmits a context window from VS Code to the Code Suggestions ML model for inference, +and the generated suggestion is transmitted back to VS Code. + +### Data privacy + +Code Suggestions operate completely in the GitLab.com infrastructure, providing the same level of +[security](https://about.gitlab.com/security/) as any other feature of GitLab.com, and processing any personal +data in accordance with our [Privacy Statement](https://about.gitlab.com/privacy/). + +No new additional data is collected to enable this feature. The content of your GitLab hosted source code is +not used as training data. Source code inference against the Code Suggestions model is not used to re-train the model. +Your data also never leaves GitLab.com. All training and inference is done in GitLab.com infrastructure. + +[Read more about the security of GitLab.com](https://about.gitlab.com/security/faq/). + +### Training data + +Code Suggestions uses open source pre-trained base models from the +[CodeGen family](https://openreview.net/forum?id=iaYcJKpY2B_) including CodeGen-MULTI and CodeGen-NL. +We then re-train and fine-tune these base models with a customized open source dataset to enable multi-language +support and additional use cases. This customized dataset contains non-preprocessed open source code in 13 +programming languages from [The Pile](https://pile.eleuther.ai/) and the +[Google BigQuery source code dataset](https://cloud.google.com/blog/topics/public-datasets/github-on-bigquery-analyze-all-the-open-source-code). +We then process this raw dataset against heuristics that aim to increase the quality of the dataset. + +The Code Suggestions model is not trained on GitLab customer data. + +### Off by default + +Code Suggestions are off by default and require a group owner to enable the feature with a group-level setting. + +After the group-level setting is enabled, developers using Visual Studio Code with the +[GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) can connect +to GitLab.com by using a GitLab +[personal access token](../../profile/personal_access_tokens.md#create-a-personal-access-token) with the `read_api` +and `read_user` scopes. + +## Progressive enhancement + +This feature is designed as a progressive enhancement to the existing VS Code GitLab Workflow plugin. +Code Suggestions offer a completion if the machine learning engine can generate a recommendation. +In the event of a connection issue or model inference failure, the feature gracefully degrades. +Code Suggestions do not prevent you from writing code in VS Code. + +### Internet connectivity + +Code Suggestions only work when you have internet connectivity and can access GitLab.com. +Code Suggestions are not available for self-managed customers, nor customers operating within an offline environment. + +### Stability and performance + +This feature is currently in [Beta](/ee/policy/alpha-beta-support.md#beta). +While the Code Suggestions inference API operates completely within the GitLab.com enterprise infrastructure, +we expect a high demand for this Beta feature, which may cause degraded performance or unexpected downtime +of the feature. We have built this feature to gracefully degrade and have controls in place to allow us to +mitigate abuse or misuse. GitLab may disable this feature for any or all customers at any time at our discretion. + +### Model accuracy and quality + +While in Beta, Code Suggestions can generate low-quality, incomplete, and possibly insecure code. +We strongly encourage all beta users to leverage GitLab native +[Code Quality Scanning](../../../ci/testing/code_quality.md) and +[Security Scanning](../../application_security/index.md) capabilities. + +GitLab uses a customized open source dataset to fine-tune the model to support multiple languages. +Based on the languages you code in, GitLab routes the request to a targeted inference and prompt engine +to get relevant suggestions. + +GitLab is actively refining these models to: + +- Improve the quality of recommendations. +- Add support for more languages. +- Add protections to limit personal data, insecure code, and other unwanted behavior + that the model may have learned from training data. + +## Known limitations + +While in Beta, we are working on improving the accuracy of overall generated content. +However, Code Suggestions may generate suggestions that are: + +- Low-quality +- Incomplete +- Produce failed pipelines +- Insecure code +- Offensive or insensitive + +We are also aware of specific situations that can produce unexpected or incoherent results including: + +- Suggestions based on natural language code comments. +- Suggestions that mixed programming languages in unexpected ways. + +## Feedback + +Report issues in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/405152). diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index f9a5d4e3aa7..e22dc549a4a 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -1,42 +1,28 @@ --- stage: Create -group: Editor +group: IDE info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' --- # File finder **(FREE)** -The file finder feature allows you to search for a file in a repository using the -GitLab UI. To use it: +With file finder, you can search for a file in a repository directly from the GitLab UI. -1. Go to your project's **Repository > Files**. -1. In the upper right corner, select **Find File**. +File finder is powered by the [`fuzzaldrin-plus`](https://github.com/jeancroy/fuzz-aldrin-plus) library, which uses fuzzy search and highlights results as you type. -If you prefer to keep your fingers on the keyboard, use the -[shortcut button](../../shortcuts.md), which you can invoke from anywhere -in a project. +## Search for a file -Press `t` to launch the File search function when in **Issues**, -**Merge requests**, **Milestones**, even the project's settings. +To search for a file: -Start typing what you are searching for and watch the magic happen. With the -up/down arrows, you go up and down the results, with `Esc` you close the search -and go back to **Files** +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Files**. +1. In the upper right, select **Find file**. +1. In the search box, start typing the filename. +1. From the dropdown list, select the file. -## How it works +To go to file finder, you can also press <kbd>t</kbd> anywhere in your project. +To go back to **Files**, press <kbd>Esc</kbd>. -The File finder feature is powered by the [Fuzzy filter](https://github.com/jeancroy/fuzz-aldrin-plus) library. - -It implements a fuzzy search with the highlight and tries to provide intuitive -results by recognizing patterns that people use while searching. - -For example, consider the [GitLab FOSS repository](https://gitlab.com/gitlab-org/gitlab-foss/tree/master) and that we want to open -the `app/controllers/admin/deploy_keys_controller.rb` file. - -Using a fuzzy search, we start by typing letters that get us closer to the file. - -NOTE: -To narrow down your search, include `/` in your search terms. +To narrow down your results, include `/` in your search.  diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 929751b7247..74d765fa7fe 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/forking_workflow.html' --- # Project forking workflow **(FREE)** @@ -16,14 +15,14 @@ A fork is a personal copy of the repository and all its branches, which you crea in a namespace of your choice. Make changes in your own fork and submit them through a merge request to the repository you don't have access to. -## Creating a fork +## Create a fork > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15013) a new form in GitLab 13.11 [with a flag](../../../user/feature_flags.md) named `fork_project_form`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77181) in GitLab 14.8. Feature flag `fork_project_form` removed. To fork an existing project in GitLab: -1. On the project's home page, in the upper right, select **{fork}** **Fork**: +1. On the project's homepage, in the upper-right corner, select **Fork** (**{fork}**):  1. Optional. Edit the **Project name**. 1. For **Project URL**, select the [namespace](../../namespace/index.md) @@ -39,10 +38,51 @@ GitLab creates your fork, and redirects you to the new fork's page. ## Update your fork -To copy the latest changes from the upstream repository into your fork, update it -[from the command line](#from-the-command-line). GitLab Premium and higher tiers can also -[configure forks as pull mirrors](#with-repository-mirroring) -of the upstream repository. +A fork can fall out of sync with its upstream repository, and require an update: + +- **Ahead**: Your fork contains new commits not present in the upstream repository. + To sync your fork, create a merge request to push your changes to the upstream repository. +- **Behind**: The upstream repository contains new commits not present in your fork. + To sync your fork, pull the new commits into your fork. +- **Ahead and behind**: Both the upstream repository and your fork contain new commits + not present in the other. To fully sync your fork, create a merge request to push + your changes up, and pull the upstream repository's new changes into your fork. + +To sync your fork with its upstream repository, update it from the GitLab UI +or the command line. GitLab Premium and Ultimate tiers can also automate updates by +[configuring forks as pull mirrors](#with-repository-mirroring) of the upstream repository. + +### From the UI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `synchronize_fork`. Disabled by default, but enabled for projects in the `gitlab-org/gitlab` and `gitlab-com/www-gitlab-com` namespaces only. + +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 `synchronize_fork`. +On GitLab.com, this feature is available for projects in the `gitlab-org/gitlab` and `gitlab-com/www-gitlab-com` namespaces. + +To update your fork from the GitLab UI: + +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the secondary menu, select **Personal**. +1. Select the fork you want to update. +1. Below the dropdown list for branch name, find the **Forked from** (**{fork}**) + information box to determine if your fork is ahead, behind, or both. In this example, + the fork is behind the upstream repository: + +  + +1. If your fork is **ahead** of the upstream repository, select + **Create merge request** to propose adding your fork's changes to the upstream repository. +1. If your fork is **behind** the upstream repository, select **Update fork** + to pull changes from the upstream repository. +1. If your fork is **ahead and behind** the upstream repository, you can update from the UI + available only if no merge conflicts are detected: + - If your fork contains no merge conflicts, you can select **Create merge request** + to propose pushing your changes to the upstream repository, **Update fork** + to pull changes down to your fork, or both. The type of changes in your fork + determine which actions are appropriate. + - If your fork contains merge conflicts, update your fork from the command line. ### From the command line @@ -102,7 +142,7 @@ an `upstream` remote repository for your fork: A fork can be configured as a mirror of the upstream if all these conditions are met: -1. Your subscription is **(PREMIUM)** or a higher tier. +1. Your subscription is **Premium** or **Ultimate**. 1. You create all changes in branches (not `main`). 1. You do not work on [merge requests for confidential issues](../merge_requests/confidential.md), which requires changes to `main`. @@ -114,7 +154,7 @@ For instructions, read [Configure pull mirroring](mirror/pull.md#configure-pull- WARNING: With mirroring, before approving a merge request, you are asked to sync. You should automate it. -## Merging upstream +## Merge changes back upstream When you are ready to send your code back to the upstream project, [create a merge request](../merge_requests/creating_merge_requests.md). For **Source branch**, @@ -129,11 +169,55 @@ Then you can add labels, a milestone, and assign the merge request to someone wh your changes. Then select **Submit merge request** to conclude the process. When successfully merged, your changes are added to the repository and branch you're merging into. -## Removing a fork relationship +## Unlink a fork -You can unlink your fork from its upstream project in the [advanced settings](../settings/index.md#remove-a-fork-relationship). +Removing a fork relationship unlinks your fork from its upstream project. +Your fork then becomes an independent project. + +Prerequisites: + +- You must be a project owner to unlink a fork. + +WARNING: +If you remove a fork relationship, you can't send merge requests to the source. +If anyone has forked your project, their fork also loses the relationship. +To restore the fork relationship, [use the API](../../../api/projects.md#create-a-forked-fromto-relation-between-existing-projects). + +To remove a fork relationship: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced**. +1. In the **Remove fork relationship** section, select **Remove fork relationship**. +1. To confirm, enter the project path and select **Confirm**. + +When you unlink a fork that uses a [hashed storage pool](../../../administration/repository_storage_types.md#hashed-object-pools) +to share objects with another repository: + +- All objects are copied from the pool into your fork. +- After the copy process completes, no further updates from the storage pool are propagated to your fork. ## Related topics -- GitLab blog post: [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). -- GitLab community forum: [Refreshing a fork](https://forum.gitlab.com/t/refreshing-a-fork/). +- GitLab blog post: [Keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/) +- GitLab community forum: [Refreshing a fork](https://forum.gitlab.com/t/refreshing-a-fork/32469) + +## Troubleshooting + +### Error: `An error occurred while forking the project. Please try again` + +This error can be due to a mismatch in shared runner settings between the forked project +and the new namespace. See [Forks](../../../ci/runners/configure_runners.md#forks) +in the Runner documentation for more information. + +### Removing fork relationship fails + +If removing the fork through the UI or API is not working, you can attempt the +fork relationship removal in a +[Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session): + +```ruby +p = Project.find_by_full_path('<project_path>') +u = User.find_by_username('<username>') +Projects::UnlinkForkService.new(p, u).execute +``` diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 78fcdec2a0b..fbf29bddd46 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -14,7 +14,7 @@ commit hash. To view it for a file: 1. Go to your project's **Repository > Files**. 1. Select the file you want to review. -1. In the upper right corner, select **Blame**. +1. In the upper-right corner, select **Blame**. When you select **Blame**, this information is displayed: diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 321b9a5eb53..a9228b8cabd 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -12,7 +12,7 @@ Git file History provides information about the commit history associated with a file. To use it: 1. Go to your project's **Repository > Files**. -1. In the upper right corner, select **History**. +1. In the upper-right corner, select **History**. When you select **History**, this information is displayed: diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 64f19d1a92c..a2dd2488961 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -43,7 +43,7 @@ To view a user's public GPG key, you can either: - Go to `https://gitlab.example.com/<USERNAME>.gpg`. GitLab displays the GPG key, if the user has configured one, or a blank page for users without a configured GPG key. -- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the upper right +- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the upper-right corner of the user's profile, select **View public GPG keys** (**{key}**). ## Configure commit signing diff --git a/doc/user/project/repository/img/update-fork_v15_11.png b/doc/user/project/repository/img/update-fork_v15_11.png Binary files differnew file mode 100644 index 00000000000..244868d80ae --- /dev/null +++ b/doc/user/project/repository/img/update-fork_v15_11.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 5b4e1b14489..9f0c46591b9 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -25,7 +25,7 @@ You can add files to a repository: - When you create a project. - After you create a project: - By using [the web editor](web_editor.md). - - [From the command line](../../../gitlab-basics/command-line-commands.md). + - From the command line. ## Commit changes to a repository @@ -235,9 +235,9 @@ The size can differ slightly from one instance to another due to compression, ho Administrators can set a [repository size limit](../../admin_area/settings/account_and_limit_settings.md). [GitLab sets the size limits for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). -## Repository contributor graph +## Repository contributor statistics -All code contributors are displayed under your project's **Repository > Contributors**. +All code contributors are displayed under your project's **Repository > Contributor statistics**. The graph shows the contributor with the most commits to the fewest. @@ -277,15 +277,15 @@ to fetch configuration from a project that is renamed or moved. ## Related topics -- [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). -- [Create a directory](web_editor.md#create-a-directory). -- [Find file history](git_history.md). -- [Identify changes by line (Git blame)](git_blame.md). -- [Use Jupyter notebooks with GitLab](jupyter_notebooks/index.md). +- [GitLab Workflow VS Code extension](vscode.md) +- [Lock files and prevent change conflicts](../file_lock.md) +- [Repository API](../../../api/repositories.md) +- [Find files](file_finder.md) +- [Branches](branches/index.md) +- [Create a directory](web_editor.md#create-a-directory) +- [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 diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 28f0ffb6fbd..1526c7b4dc2 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -25,7 +25,7 @@ GitLab. ## Cleaner diffs and raw diffs -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 as an [Alpha](../../../../policy/alpha-beta-support.md#alpha-features) release [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Enabled by default. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 as an [Experiment](../../../../policy/alpha-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75500) in GitLab 14.9. Feature flag `jupyter_clean_diffs` removed. > - [Reintroduced toggle](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85079) in GitLab 15.0 [with a flag](../../../../administration/feature_flags.md) named `ipynb_semantic_diff`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95373) in GitLab 15.6. Feature flag `ipynb_semantic_diff` removed. diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index 9942469dd5c..0563f747e8d 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- # Bidirectional mirroring **(PREMIUM)** @@ -168,4 +167,4 @@ Read about [Git Fusion settings on Perforce.com](https://www.perforce.com/manual ## Related topics -- [Configure server hooks](../../../../administration/server_hooks.md) on a GitLab server. +- [Configure server hooks](../../../../administration/server_hooks.md) diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 7a50c294dfc..9f72b8f29b2 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- # Repository mirroring **(FREE)** @@ -107,13 +106,14 @@ To use this option, select **Only mirror protected branches** when you create a ## Mirror specific branches -> Mirroring branches matching a regex [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102608) in GitLab 15.8 [with a flag](../../../../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default. +> - Mirroring branches matching a regex [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102608) in GitLab 15.8 [with a flag](../../../../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 16.0. FLAG: -On self-managed GitLab, by default the field `mirror_branch_regex` is not available. -To make it available, ask an administrator to [enable the feature flag](../../../../administration/feature_flags.md) +On self-managed GitLab, by default the field `mirror_branch_regex` is available. +To hide the feature, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) named `mirror_only_branches_match_regex`. -On GitLab.com, this feature is not available. +On GitLab.com, this feature is available. To mirror only branches with names matching an [re2 regular expression](https://github.com/google/re2/wiki/Syntax), enter a regular expression into the **Mirror specific branches** field. Branches with names that @@ -331,6 +331,29 @@ and requires the full version including the protocol (`ssh://git@gitlab.com/gitl Make sure that host and project path are separated using `/` instead of `:`. +### Host key verification failed + +This error is returned when the target host public SSH key changes. +Public SSH keys rarely, if ever, change. If host key verification fails, +but you suspect the key is still valid, you can refresh the key's information. + +Prerequisites: + +- You must have at least the Maintainer role for a project. + +To resolve the issue: + +1. [Verify the host key](#verify-a-host-key). +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Mirroring repositories**. +1. To refresh the keys, either: + + - Select **Detect host keys** for GitLab to fetch the host keys from the server, and display the fingerprints. + - Select **Input host keys manually**, and enter the host key into the **SSH host key** field. + +- Select **Mirror repository**. + ### Transfer mirror users and tokens to a single service account in Rails console This requires access to the [GitLab Rails console](../../../../administration/operations/rails_console.md#starting-a-rails-console-session). diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 0eb51f40208..2b8470b9e3d 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- # Pull from a remote repository **(PREMIUM)** @@ -142,6 +141,5 @@ end ## Related topics -- Configure [pull mirroring intervals](../../../../administration/instance_limits.md#pull-mirroring-interval) - on self-managed instances. -- Configure [pull mirroring through the API](../../../../api/projects.md#configure-pull-mirroring-for-a-project). +- [Pull mirroring intervals](../../../../administration/instance_limits.md#pull-mirroring-interval) +- [Pull mirroring API](../../../../api/projects.md#configure-pull-mirroring-for-a-project) diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index f06dd747897..11093958650 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- # Push mirroring **(FREE)** @@ -26,8 +25,10 @@ When you push a change to the upstream repository, the push mirror receives it: - Within five minutes. - Within one minute, if you enabled **Only mirror protected branches**. -In the case of a diverged branch, an error displays in the **Mirroring repositories** -section. +When a branch is merged into the default branch and deleted in the source project, +it is deleted from the remote mirror on the next push. Branches with unmerged +changes are kept. If a branch diverges, the **Mirroring repositories** section +displays an error. ## Configure push mirroring @@ -194,4 +195,4 @@ If it isn't working correctly, a red `error` tag appears, and shows the error me ## Related topics -- [Remote mirrors API](../../../../api/remote_mirrors.md). +- [Remote mirrors API](../../../../api/remote_mirrors.md) diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index 7ae085812ae..28afba375fc 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -13,7 +13,7 @@ can and can't be pushed to your repository. While GitLab offers - Evaluating the contents of a commit. - Confirming commit messages match expected formats. -- Enforcing branch name rules. +- Enforcing [branch name rules](branches/index.md#name-your-branch). - Evaluating the details of files. - Preventing Git tag removal. diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index cf7d4f44aad..4bebe4c1a97 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -22,16 +22,27 @@ Rewriting repository history is a destructive operation. Make sure to back up yo you begin. The best way to back up a repository is to [export the project](../settings/import_export.md#export-a-project-and-its-data). +## Calculate repository size + +The size of a repository is determined by computing the accumulated size of all files in the repository. +It is similar to executing `du --summarize --bytes` on your repository's +[hashed storage path](../../../administration/repository_storage_types.md). + ## Purge files from repository history -To reduce the size of your repository in GitLab, you must first remove references to large files from branches, tags, *and* -other internal references (refs) that are automatically created by GitLab. These refs include: +GitLab [prunes unreachable objects](../../../administration/housekeeping.md#prune-unreachable-objects) +as part of housekeeping. In GitLab, to reduce the disk size of your repository manually, you must +first remove references to large files from branches, tags, *and* other internal references (refs) +created by GitLab. These refs include: -- `refs/merge-requests/*` for merge requests. -- `refs/pipelines/*` for - [pipelines](../../../ci/troubleshooting.md#fatal-reference-is-not-a-tree-error). -- `refs/environments/*` for environments. -- `refs/keep-around/*` are created as hidden refs to prevent commits referenced in the database from being removed +- `refs/merge-requests/*` +- `refs/pipelines/*` +- `refs/environments/*` +- `refs/keep-around/*` + +NOTE: +For details on each of these references, see +[GitLab-specific references](../../../development/gitaly.md#gitlab-specific-references). These refs are not automatically downloaded and hidden refs are not advertised, but we can remove these refs using a project export. diff --git a/doc/user/project/repository/tags/img/tag-display_v15_9.png b/doc/user/project/repository/tags/img/tag-display_v15_9.png Binary files differnew file mode 100644 index 00000000000..015df07d025 --- /dev/null +++ b/doc/user/project/repository/tags/img/tag-display_v15_9.png diff --git a/doc/user/project/repository/tags/img/tags_commits_view_v15_10.png b/doc/user/project/repository/tags/img/tags_commits_view_v15_10.png Binary files differnew file mode 100644 index 00000000000..247d2f368d5 --- /dev/null +++ b/doc/user/project/repository/tags/img/tags_commits_view_v15_10.png diff --git a/doc/user/project/repository/tags/index.md b/doc/user/project/repository/tags/index.md new file mode 100644 index 00000000000..e252a9a433b --- /dev/null +++ b/doc/user/project/repository/tags/index.md @@ -0,0 +1,120 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Tags **(FREE)** + +In Git, a tag marks an important point in a repository's history. +Git supports two types of tags: + +- **Lightweight tags** point to specific commits, and contain no other information. + Also known as soft tags. Create or remove them as needed. +- **Annotated tags** contain metadata, can be signed for verification purposes, + and can't be changed. + +The creation or deletion of a tag can be used as a trigger for automation, including: + +- Using a [webhook](../../integrations/webhook_events.md#tag-events) to automate actions + like Slack notifications. +- Signaling a [repository mirror](../mirror/index.md) to update. +- Running a CI/CD pipeline with [`if: $CI_COMMIT_TAG`](../../../../ci/jobs/job_control.md#common-if-clauses-for-rules). + +When you [create a release](../../releases/index.md), +GitLab also creates a tag to mark the release point. +Many projects combine an annotated release tag with a stable branch. Consider +setting deployment or release tags automatically. + +In the GitLab UI, each tag displays: + + + +- The tag name. (**{tag}**) +- Optional. If the tag is [protected](../../protected_tags.md), a **protected** badge. +- The commit SHA (**{commit}**), linked to the commit's contents. +- The commit's title and creation date. +- Optional. A link to the release (**{rocket}**). +- Optional. If a pipeline has been run, the current pipeline status. +- Download links to the source code and artifacts linked to the tag. +- A [**Create release**](../../releases/index.md#create-a-release) (**{pencil}**) link. +- A link to delete the tag. + +## View tags for a project + +To view all existing tags for a project: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Tags**. + +## View tagged commits in the commits list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18795) in GitLab 15.10. + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Commits**. +1. Commits with a tag are labeled with a tag icon (**{tag}**) and the name of the tag. + This example shows a commit tagged `v1.26.0`: + +  + +To view the list of commits in this tag, select the tag name. + +## Create a tag + +Tags can be created from the command line, or the GitLab UI. + +### From the command line + +To create either a lightweight or annotated tag from the command line, and push it upstream: + +1. To create a lightweight tag, run the command `git tag TAG_NAME`, changing + `TAG_NAME` to your desired tag name. +1. To create an annotated tag, run one of the versions of `git tag` from the command line: + + ```shell + # In this short version, the annotated tag's name is "v1.0", + # and the message is "Version 1.0". + git tag -a v1.0 -m "Version 1.0" + + # Use this version to write a longer tag message + # for annotated tag "v1.0" in your text editor. + git tag -a v1.0 + ``` + +1. Push your tags upstream with `git push origin --tags`. + +### From the UI + +To create a tag from the GitLab UI: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Tags**. +1. Select **New tag**. +1. Provide a **Tag name**. +1. For **Create from**, select an existing branch name, tag, or commit SHA. +1. Optional. Add a **Message** to create an annotated tag, or leave blank to + create a lightweight tag. +1. Select **Create tag**. + +## Prevent tag deletion **(PREMIUM)** + +To prevent users from removing a tag with `git push`, create a [push rule](../push_rules.md). + +## Trigger pipelines from a tag + +GitLab CI/CD provides a [`CI_COMMIT_TAG` variable](../../../../ci/variables/predefined_variables.md) +to identify tags. Use this variable in job rules and workflow rules to test if the pipeline +was triggered by a tag. + +In your `.gitlab-ci.yml` file for the CI/CD pipeline configuration of your project, +you can trigger based on a new tag: + +- At the job level, with the [`only` keyword](../../../../ci/yaml/index.md#only--except). +- At the pipeline level, with the [workflow rules keywords](../../../../ci/yaml/workflow.md). + +## Related topics + +- [Tagging (Git reference page)](https://git-scm.com/book/en/v2/Git-Basics-Tagging) +- [Protected tags](../../protected_tags.md) +- [Tags API](../../../../api/tags.md) diff --git a/doc/user/project/repository/vscode.md b/doc/user/project/repository/vscode.md index 9260d59bc3a..2a33476b545 100644 --- a/doc/user/project/repository/vscode.md +++ b/doc/user/project/repository/vscode.md @@ -1,6 +1,6 @@ --- stage: Create -group: Editor +group: IDE info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -22,6 +22,7 @@ do more day-to-day tasks in Visual Studio Code, such as: and paste snippets to, and from, your editor. - [Browse repositories](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#browse-a-repository-without-cloning) without cloning them. +- [Receive Code Suggestions](code_suggestions.md) ## Download the extension @@ -34,6 +35,7 @@ you can [configure](https://marketplace.visualstudio.com/items?itemName=GitLab.g - [Features to display or hide](https://gitlab.com/gitlab-org/gitlab-vscode-extension#extension-settings). - [Self-signed certificate](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#self-signed-certificates) information. +- [Code Suggestions](code_suggestions.md) ## Report issues with the extension @@ -44,5 +46,4 @@ Report any issues, bugs, or feature requests in the - [Download the extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) - [Extension documentation](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/README.md) -- The extension source code is available in the - [`gitlab-vscode-extension`](https://gitlab.com/gitlab-org/gitlab-vscode-extension/) project. +- [View source code](https://gitlab.com/gitlab-org/gitlab-vscode-extension/) diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 80b0ada6f7b..dc988846676 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -1,6 +1,6 @@ --- stage: Create -group: Editor +group: IDE info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -26,11 +26,32 @@ for any change you commit through the Web Editor. To create a text file in the Web Editor: 1. On the top bar, select **Main menu > Projects** and find your project. -1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). +1. From the project dashboard or repository, next to the branch name, + select the plus icon (**{plus}**). 1. From the dropdown list, select **New file**. -1. Complete the fields. To create a merge request with the new file, ensure the **Start a new merge request with these changes** checkbox is selected. +1. Complete the fields. +1. To create a merge request with the new file, ensure the **Start a new merge request with these changes** checkbox is selected, if you had chosen a **Target branch** other than the [default branch (such as `main`)](../../../user/project/repository/branches/default.md). 1. Select **Commit changes**. +### Create a file from a template + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Files**. +1. Next to the project name, select the plus icon (**{plus}**) to display a + dropdown list, then select **New file** from the list. +1. For **Filename**, provide one of the filenames that GitLab provides a template for: + - `.gitignore` + - `.gitlab-ci.yml` + - `LICENSE` + - `Dockerfile` +1. Select **Apply a template**, then select the template you want to apply. +1. Make your changes to the file. +1. Provide a **Commit message**. +1. Enter a **Target branch** to merge into. To create a new merge request with + your changes, enter a branch name that is not your repository's + [default branch](../../../user/project/repository/branches/default.md), +1. Select **Commit changes** to add the commit to your branch. + ## Edit a file To edit a text file in the Web Editor: @@ -87,6 +108,9 @@ To link to a single line, you can also: To upload a binary file in the Web Editor: +<!-- This list is duplicated at doc/gitlab-basics/add-file.md#from-the-ui --> +<!-- For why we duplicated the info, see https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111072#note_1267429478 --> + 1. On the top bar, select **Main menu > Projects** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **Upload file**. @@ -115,7 +139,7 @@ To create a [branch](branches/index.md) in the Web Editor: ## Create a tag -You can create [tags](../../../topics/git/tags.md) to mark milestones such as +You can create [tags](tags/index.md) to mark milestones such as production releases and release candidates. To create a tag in the Web Editor: 1. On the top bar, select **Main menu > Projects** and find your project. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 42f7be30822..80538697100 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -32,7 +32,7 @@ For a commit or tag to be *verified* by GitLab: from the certificate in the signature to a trusted certificate in the GitLab certificate store. This chain may include intermediate certificates supplied in the signature. You may need to add certificates, such as Certificate Authority root certificates, - [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). + [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates). - The signing time must be in the time range of the [certificate validity](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5), which is usually up to three years. @@ -101,7 +101,7 @@ To configure Windows or macOS: - Downloading the installer. - Running `brew install smimesign` on macOS. 1. Get the ID of your certificate by running `smimesign --list-keys`. -1. Set your signing key by running `git config --global user.signingkey ID`. +1. Set your signing key by running `git config --global user.signingkey <ID>`, replacing `<ID>` with the certificate ID. 1. Configure X.509 with this command: ```shell @@ -342,7 +342,7 @@ step of the previous [main verification checks](#main-verification-checks). ``` 1. If this fails, add the missing certificates required to establish trust - [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). + [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates). 1. After adding more certificates, (if these troubleshooting steps then pass) run the Rake task to [re-verify commits](#re-verify-commits). diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index b04905e6b34..b8e9de41062 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Plan -group: Certify +group: Product Planning info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -24,12 +24,17 @@ If an industry standard *requires* that your application has a certain feature o [create a requirement](#create-a-requirement) to reflect this. When a feature is no longer necessary, you can [archive the related requirement](#archive-a-requirement). +NOTE: +Requirements and [test cases](../../../ci/test_cases/index.md) are being +[migrated to work items](https://gitlab.com/groups/gitlab-org/-/epics/5171). +[Issue 323790](https://gitlab.com/gitlab-org/gitlab/-/issues/323790) proposes to link requirements to test cases. +For more information, see [Product Stage Direction - Plan](https://about.gitlab.com/direction/plan/). + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [GitLab 12.10 Introduces Requirements Management](https://www.youtube.com/watch?v=uSS7oUNSEoU). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a more in-depth walkthrough using a [demonstration project](https://gitlab.com/gitlab-org/requiremeents-mgmt), -see [GitLab Requirements Traceability Walkthrough](https://youtu.be/VIiuTQYFVa0) (Feb 2021). +For a more in-depth walkthrough see [GitLab Requirements Traceability Walkthrough](https://youtu.be/VIiuTQYFVa0) (Feb 2021).  @@ -235,9 +240,9 @@ Before you import your file: To import requirements: 1. In a project, go to **Issues > Requirements**. - - If the project already has existing requirements, select the import icon (**{import}**) in the - upper right. - - For a project without any requirements, select **Import CSV** in the middle of the page. + - For a project with requirements, in the + upper-right corner, select the import icon (**{import}**). + - For a project without requirements, in the middle of the page, select **Import CSV**. 1. Select the file and select **Import requirements**. The file is processed in the background and a notification email is sent @@ -296,7 +301,7 @@ Prerequisite: To export requirements: 1. In a project, go to **Issues > Requirements**. -1. In the upper right, select the **Export as CSV** icon (**{export}**). +1. In the upper-right corner, select **Export as CSV** (**{export}**). A confirmation modal appears. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 22297149561..bd5c8214e68 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -8,29 +8,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Moved to GitLab Free in 13.2. -Service Desk is a module that allows your team to connect -with any external party through email, without any external tools. -An ongoing conversation in the same place as where your software -is built ensures user feedback ends up where it's needed. +With Service Desk, your customers +can email you bug reports, feature requests, or general feedback. +Service Desk provides a unique email address, so they don't need their own GitLab accounts. -With Service Desk, you can provide efficient email support to your customers. They can -email you bug reports, feature requests, or general feedback. They all end up in your -GitLab project as new issues. In turn, your team can respond directly from the project. +Service Desk emails are created in your GitLab project as new issues. +Your team can respond directly from the project, while customers interact with the thread only +through email. -As Service Desk is built right into GitLab itself, the complexity and inefficiencies -of multiple tools and external integrations are eliminated. This significantly shortens -the cycle time from feedback to software update. - -For an overview, check the video demonstration on [GitLab Service Desk](https://about.gitlab.com/blog/2017/05/09/demo-service-desk/). - -## How it works - -GitLab Service Desk enables people to create issues in your -GitLab instance without needing their own user account. - -It provides a unique email address for end users to create issues in a project. -Follow-up notes can be sent either through the GitLab interface or by email. End -users only see the thread through email. +## Service Desk workflow For example, let's assume you develop a game for iOS or Android. The codebase is hosted in your GitLab instance, built and deployed @@ -43,57 +29,58 @@ Here's how Service Desk works for you: 1. Each email they send creates an issue in the appropriate project. 1. Your team members go to the Service Desk issue tracker, where they can see new support requests and respond inside associated issues. -1. Your team communicates back and forth with the customer to understand the request. +1. Your team communicates with the customer to understand the request. 1. Your team starts working on implementing code to solve your customer's problem. -1. When your team finishes the implementation, whereupon the merge request is merged and the issue +1. When your team finishes the implementation, the merge request is merged and the issue is closed automatically. -1. The customer's requests are handled through email, without ever having access to your - GitLab instance. -1. Your team saved time by not having to leave GitLab (or setup any integrations) to follow up with - your customer. -## Configuring Service Desk +Meanwhile: -Users with Maintainer and higher access in a project can configure Service Desk. +- The customer interacts with your team entirely through email, without needing access to your + GitLab instance. +- Your team saves time by not having to leave GitLab (or set up integrations) to follow up with + your customer. -Service Desk issues are [confidential](issues/confidential_issues.md), so they are -only visible to project members. In GitLab 11.7 we updated the generated email -address format. The older format is still supported, so existing aliases or -contacts still work. +## Configure Service Desk -If you have [templates](description_templates.md) in your repository, you can optionally select -one from the selector menu to append it to all Service Desk issues. +To start using Service Desk for a project, you must first turn it on. +By default, Service Desk is turned off. + +Prerequisites: + +- You must have at least the Maintainer role for the project. +- On GitLab self-managed, you must [set up incoming email](../../administration/incoming_email.md#set-it-up) + for the GitLab instance. You should use + [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), + but you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). + To do this, you must have administrator access. To enable Service Desk in your project: -1. (GitLab self-managed only) [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. - You should use [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), - but you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). -1. In a project, in the left sidebar, go to **Settings > General** and expand the **Service Desk** section. -1. Enable the **Activate Service Desk** toggle. This reveals a unique email address to email issues - to the project. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Service Desk**. +1. Turn on the **Activate Service Desk** toggle. +1. Optional. Complete the fields. + - [Add a suffix](#configure-a-custom-email-address-suffix) to your Service Desk email address. + - If the list below **Template to append to all Service Desk issues** is empty, create a + [description template](description_templates.md) in your repository. +1. Select **Save changes**. -Service Desk is now enabled for this project! To access it in a project, in the left sidebar, select -**Issues > Service Desk**. +Service Desk is now enabled for this project. +If anyone sends an email to the address available below **Email address to use for Service Desk**, +GitLab creates a confidential issue with the email's content. -WARNING: -Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless -of their access level** to your GitLab instance. +### Improve your project's security -To improve your project's security, you should: +To improve your Service Desk project's security, you should: - Put the Service Desk email address behind an alias on your email system so you can change it later. - [Enable Akismet](../../integration/akismet.md) on your GitLab instance to add spam checking to this service. Unblocked email spam can result in many spam issues being created. -The unique internal email address is visible to project members at least -the Reporter role in your GitLab instance. -An external user (issue creator) cannot see the internal email address -displayed in the information note. +### Create customized email templates -### Using customized email templates - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in GitLab 12.7. > - Moved from GitLab Premium to GitLab Free in 13.2. > - `UNSUBSCRIBE_URL`, `SYSTEM_HEADER`, `SYSTEM_FOOTER`, and `ADDITIONAL_TEXT` placeholders [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285512) in GitLab 15.9. @@ -103,14 +90,6 @@ An email is sent to the author when: - A new note is created on a Service Desk issue. You can customize the body of these email messages with templates. -Save your templates in the `.gitlab/service_desk_templates/` -directory in your repository. - -With Service Desk, you can use templates for: - -- [Thank you emails](#thank-you-email) -- [New note emails](#new-note-email) -- [New Service Desk issues](#new-service-desk-issues) #### Email header and footer **(FREE SELF)** @@ -122,13 +101,18 @@ visible in the email template. For more information, see #### Thank you email +> `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. + When a user submits an issue through Service Desk, GitLab sends a **thank you email**. -You must name the template file `thank_you.md`. + +To create a custom email template, in the `.gitlab/service_desk_templates/` +directory in your repository, create a file named `thank_you.md`. You can use these placeholders to be automatically replaced in each email: - `%{ISSUE_ID}`: issue IID - `%{ISSUE_PATH}`: project path appended with the issue IID +- `%{ISSUE_DESCRIPTION}`: issue description based on the original email - `%{UNSUBSCRIBE_URL}`: unsubscribe URL - `%{SYSTEM_HEADER}`: [system header message](../admin_area/appearance.md#system-header-and-footer-messages) - `%{SYSTEM_FOOTER}`: [system footer message](../admin_area/appearance.md#system-header-and-footer-messages) @@ -139,20 +123,28 @@ the response email does not contain the issue link. #### New note email +> `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. + When a user-submitted issue receives a new comment, GitLab sends a **new note email**. -You must name the template file `new_note.md`. + +To create a custom email template, in the `.gitlab/service_desk_templates/` +directory in your repository, create a file named `new_note.md`. You can use these placeholders to be automatically replaced in each email: - `%{ISSUE_ID}`: issue IID - `%{ISSUE_PATH}`: project path appended with the issue IID +- `%{ISSUE_DESCRIPTION}`: issue description at the time email is generated. + If a user has edited the description, it might contain sensitive information that is not intended + to be delivered to external participants. Use this placeholder only if you never modify + descriptions or your team is aware of the template design. - `%{NOTE_TEXT}`: note text - `%{UNSUBSCRIBE_URL}`: unsubscribe URL - `%{SYSTEM_HEADER}`: [system header message](../admin_area/appearance.md#system-header-and-footer-messages) - `%{SYSTEM_FOOTER}`: [system footer message](../admin_area/appearance.md#system-header-and-footer-messages) - `%{ADDITIONAL_TEXT}`: [custom additional text](../admin_area/settings/email.md#custom-additional-text) -#### New Service Desk issues +### Use a custom template for Service Desk issues You can select one [description template](description_templates.md#create-an-issue-template) **per project** to be appended to every new Service Desk issue's description. @@ -165,57 +157,65 @@ You can set description templates at various levels: The templates are inherited. For example, in a project, you can also access templates set for the instance, or the project's parent groups. +Prerequisite: + +- You must have [created a description template](description_templates.md#create-an-issue-template). + To use a custom description template with Service Desk: 1. On the top bar, select **Main menu > Projects** and find your project. -1. [Create a description template](description_templates.md#create-an-issue-template). -1. On the left sidebar, select **Settings > General > Service Desk**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Service Desk**. 1. From the dropdown list **Template to append to all Service Desk issues**, search or select your template. -### Using a custom email display name +### Support Bot user + +Behind the scenes, Service Desk works by the special Support Bot user creating issues. +This user isn't a [billable user](../../subscriptions/self_managed/index.md#billable-users), +so it does not count toward the license limit count. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7529) in GitLab 12.8. +#### Change the Support Bot's display name -You can customize the email display name. Emails sent from Service Desk have +You can change the display name of the Support Bot user. Emails sent from Service Desk have this name in the `From` header. The default display name is `GitLab Support Bot`. To edit the custom email display name: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General > Service Desk**. -1. Enter a new name in **Email display name**. -1. Select **Save Changes**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Service Desk**. +1. Below **Email display name**, enter a new name. +1. Select **Save changes**. -### Using a custom email address **(FREE SELF)** +### Use a custom email address **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. -It is possible to customize the email address used by Service Desk. To do this, you must configure -a [custom mailbox](#configuring-a-custom-mailbox). If you want you can also configure a -[custom suffix](#configuring-a-custom-email-address-suffix). +You can use a custom email address with Service Desk. -#### Configuring a custom mailbox +To do this, you must configure +a [custom mailbox](#configure-a-custom-mailbox). You can also configure a +[custom suffix](#configure-a-custom-email-address-suffix). + +#### Configure a custom mailbox NOTE: On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address, you can still configure the -[custom suffix](#configuring-a-custom-email-address-suffix) in project settings. +[custom suffix](#configure-a-custom-email-address-suffix) in project settings. Service Desk uses the [incoming email](../../administration/incoming_email.md) configuration by default. However, by using the `service_desk_email` configuration, you can customize the mailbox used by Service Desk. This allows you to have -a separate email address for Service Desk by also configuring a [custom suffix](#configuring-a-custom-email-address-suffix) +a separate email address for Service Desk by also configuring a [custom suffix](#configure-a-custom-email-address-suffix) in project settings. -The `address` must include the `+%{key}` placeholder in the 'user' -portion of the address, before the `@`. The placeholder is used to identify the project -where the issue should be created. +Prerequisites: -NOTE: -When configuring a custom mailbox, the `service_desk_email` and `incoming_email` -configurations must always use separate mailboxes. It's important, because -emails picked from `service_desk_email` mailbox are processed by a different -worker and it would not recognize `incoming_email` emails. +- The `address` must include the `+%{key}` placeholder in the `user` portion of the address, + before the `@`. The placeholder is used to identify the project where the issue should be created. +- The `service_desk_email` and `incoming_email` configurations must always use separate mailboxes + to make sure Service Desk emails are processed correctly. To configure a custom mailbox for Service Desk with IMAP, add the following snippets to your configuration file in full: @@ -274,7 +274,7 @@ The configuration options are the same as for configuring > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9. Instead of having the Service Desk email credentials stored in plaintext in the configuration files, you can optionally -use an encrypted file for the Incoming email credentials. +use an encrypted file for the incoming email credentials. Prerequisites: @@ -403,7 +403,8 @@ read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secre > - Alternative Azure deployments [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5978) in GitLab 14.9. Service Desk can be configured to read Microsoft Exchange Online mailboxes with the Microsoft -Graph API instead of IMAP. Follow the [documentation in the incoming email section for setting up an OAuth 2.0 application for Microsoft Graph](../../administration/incoming_email.md#microsoft-graph). +Graph API instead of IMAP. Set up an OAuth 2.0 application for Microsoft Graph +[the same way as for incoming email](../../administration/incoming_email.md#microsoft-graph). - Example for Omnibus GitLab installations: @@ -422,32 +423,44 @@ Graph API instead of IMAP. Follow the [documentation in the incoming email secti } ``` -For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), configure the `azure_ad_endpoint` and `graph_endpoint` settings. +For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), +configure the `azure_ad_endpoint` and `graph_endpoint` settings. - Example for Microsoft Cloud for US Government: ```ruby - gitlab_rails['service_desk_email_inbox_options'] = { - 'azure_ad_endpoint': 'https://login.microsoftonline.us', - 'graph_endpoint': 'https://graph.microsoft.us', - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional - } +gitlab_rails['service_desk_email_inbox_options'] = { + 'azure_ad_endpoint': 'https://login.microsoftonline.us', + 'graph_endpoint': 'https://graph.microsoft.us', + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional } ``` -The Microsoft Graph API is not yet supported in source installations. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/326169) for more details. +The Microsoft Graph API is not yet supported in source installations. +For more information, see [issue 326169](https://gitlab.com/gitlab-org/gitlab/-/issues/326169). -#### Configuring a custom email address suffix +#### Configure a custom email address suffix -You can set a custom suffix in your project's Service Desk settings after you have configured a [custom mailbox](#configuring-a-custom-mailbox). -It can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). +You can set a custom suffix in your project's Service Desk settings. + +A suffix can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). When configured, the custom suffix creates a new Service Desk email address, consisting of the `service_desk_email_address` setting and a key of the format: `<project_full_path>-<custom_suffix>` +Prerequisites: + +- You must have configured a [custom mailbox](#configure-a-custom-mailbox). + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Service Desk**. +1. Below **Email address suffix**, enter the suffix to use. +1. Select **Save changes**. + For example, suppose the `mygroup/myproject` project Service Desk settings has the following configured: - Email address suffix is set to `support`. @@ -456,13 +469,23 @@ For example, suppose the `mygroup/myproject` project Service Desk settings has t The Service Desk email address for this project is: `contact+mygroup-myproject-support@example.com`. The [incoming email](../../administration/incoming_email.md) address still works. -If you don't configure the custom suffix, the default project identification is used for identifying the project. You can see that email address in the project settings. +If you don't configure a custom suffix, the default project identification is used for identifying +the project. -## Using Service Desk +## Use Service Desk You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue). In these issues, you can also see our friendly neighborhood [Support Bot](#support-bot-user). +### View Service Desk email address + +To check what the Service Desk email address is for your project: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues > Service Desk**. + +The email address is available at the top of the issue list. + ### 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. @@ -502,39 +525,51 @@ You can read and write comments as you usually do in GitLab: - The project's visibility (private, internal, public) does not affect Service Desk. - The path to the project, including its group or namespace, is shown in emails. -#### Receiving files attached to comments as email attachments +#### View Service Desk issues -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default. +Prerequisites: -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. -On GitLab.com, this feature is not available. +- You must have at least the Reporter role for the project. -If a comment contains any attachments and their total size is less than or equal to 10 MB, these -attachments are sent as part of the email. In other cases, the email contains links to the attachments. +To view Service Desk issues: -#### Special HTML formatting in HTML emails +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues > Service Desk**. -<!-- When the feature flag is removed, delete this topic and add as a line in version history under one of the topics above this one.--> +### Email contents and formatting -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372301) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default. +#### Special HTML formatting in HTML emails -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. -On GitLab.com, this feature is not available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109811) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116809) in GitLab 15.11. Feature flag `service_desk_html_to_text_email_handler` removed. -When this feature is enabled, HTML emails correctly show additional HTML formatting, such as: +HTML emails show HTML formatting, such as: - Tables - Blockquotes - Images - Collapsible sections -#### Privacy considerations +#### Files attached to comments + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/386860) in GitLab 15.10. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. +On GitLab.com, this feature is available. + +If a comment contains any attachments and their total size is less than or equal to 10 MB, these +attachments are sent as part of the email. In other cases, the email contains links to the attachments. + +In GitLab 15.9 and earlier, uploads to a comment are sent as links in the email. + +## Privacy considerations > [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108901) the minimum required role to view the creator's and participant's email in GitLab 15.9. -Service Desk issues are confidential, but the project owner can +Service Desk issues are [confidential](issues/confidential_issues.md), so they are +only visible to project members. The project owner can [make an issue public](issues/confidential_issues.md#modify-issue-confidentiality). When a Service Desk issue becomes public, the issue creator's and participants' email addresses are visible to signed-in users with at least the Reporter role for the project. @@ -542,17 +577,18 @@ visible to signed-in users with at least the Reporter role for the project. In GitLab 15.8 and earlier, when a Service Desk issue becomes public, the issue creator's email address is disclosed to everyone who can view the project. -### Support Bot user +Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless +of their role** in the project. -Behind the scenes, Service Desk works by the special Support Bot user creating issues. This user -does not count toward the license limit count. +The unique internal email address is visible to project members at least +the Reporter role in your GitLab instance. +An external user (issue creator) cannot see the internal email address +displayed in the information note. ### Moving a Service Desk issue > [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/372246) in GitLab 15.7: customers continue receiving notifications when a Service Desk issue is moved. -Service Desk issues can be moved like any other issue in GitLab. - You can move a Service Desk issue the same way you [move a regular issue](issues/managing_issues.md#move-an-issue) in GitLab. @@ -567,8 +603,3 @@ in both issues. They continue to receive any notifications in the old issue and Your emails might be ignored because they contain one of the [email headers that GitLab ignores](../../administration/incoming_email.md#rejected-headers). - -### Responses to a Service Desk issue do not generate emails - -Your issue might have been moved to a different project. -Moved Service Desk issues do not retain email participants. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 3715eef08e0..958246908bc 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -1,46 +1,70 @@ --- stage: Manage -group: Import +group: Import and Integrate info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Migrating projects using file exports **(FREE)** Existing projects on any self-managed GitLab instance or GitLab.com can be exported to a file and -then imported into a new GitLab instance. You can also: +then imported into another GitLab instance. You can also copy GitLab projects to another location with more automation by +[migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). -- [Migrate groups](../../group/import/index.md) using the preferred method. -- [Migrate groups using file exports](../../group/settings/import_export.md). +## Preserving user contributions -GitLab maps user contributions correctly when an admin access token is used to perform the import. +Preserving user contribution depends on meeting the following requirements: -Consequently, migrating projects using file exports does not map user contributions correctly when you are importing -projects from a self-managed instance to GitLab.com. +### Migrating from GitLab self-managed to GitLab.com -Instead, all GitLab user associations (such as comment author) are changed to the user importing the project. For more -information, see the prerequisites and important notes in these sections: +When migrating projects by using file exports, an administrator's access token is required for user contributions to map correctly. -- [Export a project and its data](../settings/import_export.md#export-a-project-and-its-data). -- [Import the project](../settings/import_export.md#import-a-project-and-its-data). +Therefore, user contributions never map correctly when importing file exports from a self-managed instance to GitLab.com. Instead, all GitLab user associations (such as +comment author) are changed to the user importing the project. To preserve contribution history, do one of the following: -To preserve contribution history, [migrate using direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). +- [Migrate by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). +- Consider paid GitLab [migration services](https://about.gitlab.com/services/migration/). -If you migrate from GitLab.com to self-managed GitLab, an administrator can create users on the self-managed GitLab instance. +### Migrating to GitLab self-managed + +To ensure GitLab maps users and their contributions correctly: + +- The owner of the project's top-level group should export the project so that the information of all members (direct and inherited) with access to the project can be included in the exported file. Project maintainers and owners can initiate the project export. However, only direct members of a project are then exported. +- An administrator must perform the import with an administrator access token. +- Required users must exist on the destination GitLab instance. An administrator can create confirmed users either in bulk in a Rails console or one by one in the UI. +- Users must [set a public email in their profiles](../../profile/index.md#set-your-public-email) on the source GitLab instance that matches their primary email + address on the destination GitLab instance. You can also manually add users' public emails by + [editing project export files](#edit-project-export-files). + +When the email of an existing user matches the email of an imported user, that user is added as a [direct member](../members/index.md) to the imported project. + +If any of the previous conditions are not met, user contributions are not mapped correctly. Instead, all GitLab user associations are changed to the user who performed the import. +That user becomes an author of merge requests created by other users. Supplementary comments mentioning original authors are: + +- Added for comments, merge request approvals, linked tasks, and items. +- Not added for the merge request or issue creator, added or removed labels, and merged-by information. + +## Edit project export files + +You can add or remove data from export files. For example, you can: + +- Manually add users public emails to the `project_members.ndjson` file. +- Trim CI pipelines by removing lines from the `ci_pipelines.ndjson` file. + +To edit a project export file: + +1. Extract the exported `.tar.gz` file. +1. Edit the appropriate file . For example, `tree/project/project_members.ndjson`. +1. Compress the files back to a `.tar.gz` file. + +You can also make sure that all members were exported by checking the `project_members.ndjson` file. ## Compatibility -FLAG: -On self-managed GitLab by default project, file exports are in NDJSON format. To make GitLab produce project file -exports in JSON format, ask an administrator to [disable the feature flags](../../../administration/feature_flags.md) -named `project_export_as_ndjson`. To allow GitLab to import project file exports in JSON format, ask an administrator to -[disable the feature flags](../../../administration/feature_flags.md) named `project_import_ndjson`. On GitLab.com, -project file exports are in NDJSON format only. +> Support for JSON-formatted project file exports [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/389888) in GitLab 15.11. -Project file exports are in NDJSON format. Before version 14.0, GitLab produced project file exports in JSON format. -To support transitions, you can still import JSON-formatted project file exports if you configure the relevant feature -flags. +Project file exports are in NDJSON format. -From GitLab 13.0, GitLab can import project file exports that were exported from a version of GitLab up to two +You can import project file exports that were exported from a version of GitLab up to two [minor](../../../policy/maintenance.md#versioning) versions behind, which is similar to our process for [security releases](../../../policy/maintenance.md#security-releases). @@ -85,7 +109,6 @@ Prerequisites: - Review the list of [items that are exported](#items-that-are-exported). Not all items are exported. - You must have at least the Maintainer role for the project. -- Users must [set a public email](../../profile/index.md#set-your-public-email) in the source GitLab instance that matches one of their verified emails in the target GitLab instance for the user mapping to work correctly. To export a project and its data, follow these steps: @@ -103,76 +126,86 @@ moved to your configured `uploads_directory`. Every 24 hours, a worker deletes t ### Items that are exported -The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) -file for projects lists many of the items exported and imported when migrating projects using file exports. View this file in the branch -for your version of GitLab to see the list of items relevant to you. For example, -[`import_export.yml` on the `14-10-stable-ee` branch](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/project/import_export.yml). +Exported project items depend on the version of GitLab you use. To determine if a +specific project item is exported: -Migrating projects with file exports uses the same export and import mechanisms as creating projects from templates at the [group](../../group/custom_project_templates.md) and -[instance](../../admin_area/custom_project_templates.md) levels. Therefore, the list of exported items is the same. +1. Check the [`exporters` array](https://gitlab.com/gitlab-org/gitlab/blob/0a60d6dcfa7b809cf4fe0c2e239f406014d92e34/app/services/projects/import_export/export_service.rb#L25-28). +1. Check the [`project/import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) file for projects for your GitLab version (for example, `<https://gitlab.com/gitlab-org/gitlab/-/blob/15-9-stable-ee/lib/gitlab/import_export/project/import_export.yml>` for GitLab 15.9). -Items that are exported include: +For a quick overview, items that are exported include: - Project and wiki repositories - Project uploads - Project configuration, excluding integrations - Issues - Issue comments - - Issue iteration ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96184) in 15.4) - - Issue resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - - Issue resource milestone events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - - Issue resource iteration events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Issue iterations ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96184) in GitLab 15.4) + - Issue resource state events ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Issue resource milestone events ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Issue resource iteration events ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - Merge requests - Merge request diffs - Merge request comments - - Merge request resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - - Merge request multiple assignees ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) - - Merge request reviewers ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) - - Merge request approvers ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) + - Merge request resource state events ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Merge request multiple assignees ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) + - Merge request reviewers ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) + - Merge request approvers ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) +- Commit comments ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391601) in GitLab 15.10) - Labels - Milestones - Snippets - Time tracking and other project entities -- Design Management files and data +- Design management files and data - LFS objects - Issue boards - Pipelines history -- Push Rules -- Awards -- Group members are exported as project members, as long as the user has the Maintainer role in the - exported project's group, or is an administrator +- Push rules +- Emoji reactions +- Group members as long as the user has the Maintainer role in the + exported project's group or is an administrator + +### Items that are not exported Items that are **not** exported include: - [Child pipeline history](https://gitlab.com/gitlab-org/gitlab/-/issues/221088) +- Pipeline triggers - Build traces and artifacts - Package and container registry images - CI/CD variables -- Pipeline triggers - Webhooks - Any encrypted tokens - [Number of required approvals](https://gitlab.com/gitlab-org/gitlab/-/issues/221087) - Repository size limits - Deploy keys allowed to push to protected branches -- Secure Files -- [Activity logs for Git-related events](https://gitlab.com/gitlab-org/gitlab/-/issues/214700). For example, pushing and creating tags +- Secure files +- [Activity logs for Git-related events](https://gitlab.com/gitlab-org/gitlab/-/issues/214700) (for example, pushing and creating tags) +- Security policies associated with your project + +Migrating projects with file exports uses the same export and import mechanisms as creating projects from templates at the [group](../../group/custom_project_templates.md) and +[instance](../../admin_area/custom_project_templates.md) levels. Therefore, the list of exported items is the same. ## Import a project and its data -> Default maximum import file size [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. +> Default maximum import file size [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. Administrators of self-managed instances can [set maximum import file size](#set-maximum-import-file-size). On GitLab.com, the value is [set to 5 GB](../../gitlab_com/index.md#account-and-limit-settings). + +You can import a project and its data. WARNING: Only import projects from sources you trust. If you import a project from an untrusted source, it may be possible for an attacker to steal your sensitive data. -Prerequisites: +### Prerequisites + +> Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. - You must have [exported the project and its data](#export-a-project-and-its-data). - Compare GitLab versions and ensure you are importing to a GitLab version that is the same or later than the GitLab version you exported to. - Review [compatibility](#compatibility) for any issues. -- At least the Maintainer role on the destination group to migrate to. Using the Developer role for this purpose was - [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. +- At least the Maintainer role on the destination group to migrate to. + +### Import a project To import a project: @@ -200,14 +233,9 @@ Deploy keys aren't imported. To use deploy keys, you must enable them in your im ### Import large projects **(FREE SELF)** -If you have a larger project, consider using a Rake task as described in the [developer documentation](../../../development/import_project.md#importing-via-a-rake-task). +If you have a larger project, consider [using a Rake task](../../../administration/raketasks/project_import_export.md#import-large-projects). -## Automate group and project import **(PREMIUM)** - -For information on automating user, group, and project import API calls, see -[Automate group and project import](../import/index.md#automate-group-and-project-import). - -## Maximum import file size +## Set maximum import file size **(FREE SELF)** Administrators can set the maximum import file size one of two ways: @@ -216,34 +244,15 @@ Administrators can set the maximum import file size one of two ways: The default is `0` (unlimited). -For the GitLab.com setting, see the [Account and limit settings](../../gitlab_com/index.md#account-and-limit-settings) -section of the GitLab.com settings page. - -## Map users for import - -Imported users can be mapped by their public email addresses on self-managed instances, if an administrator (not an owner) does the import. - -- The project must be exported by a project or group member with the Owner role. -- Public email addresses are not set by default. Users must [set it in their profiles](../../profile/index.md#set-your-public-email) - for mapping to work correctly. -- For contributions to be mapped correctly, users must be an existing member of the namespace, - or they can be added as a member of the project. Otherwise, a supplementary comment is left to mention that the original - author and the merge requests, notes, or issues that are owned by the importer. -- Imported users are set as [direct members](../members/index.md) - in the imported project. - -For project migration imports performed over GitLab.com groups, preserving author information is -possible through a [professional services engagement](https://about.gitlab.com/services/migration/). - ## Rate limits To help avoid abuse, by default, users are rate limited to: -| Request Type | Limit | -| ---------------- | ----- | -| Export | 6 projects per minute | -| Download export | 1 download per group per minute | -| Import | 6 projects per minute | +| Request type | Limit | +|:----------------|:--------------------------------| +| Export | 6 projects per minute | +| Download export | 1 download per group per minute | +| Import | 6 projects per minute | ## Related topics @@ -251,3 +260,5 @@ To help avoid abuse, by default, users are rate limited to: - [Project import and export administration Rake tasks](../../../administration/raketasks/project_import_export.md) - [Migrating GitLab groups](../../group/import/index.md) - [Group import and export API](../../../api/group_import_export.md) +- [Migrate groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). +- [Migrate groups by using file exports](../../group/import/index.md#migrate-groups-by-uploading-an-export-file-deprecated). diff --git a/doc/user/project/settings/import_export_troubleshooting.md b/doc/user/project/settings/import_export_troubleshooting.md index 00edeef5cfa..c3abfa015a6 100644 --- a/doc/user/project/settings/import_export_troubleshooting.md +++ b/doc/user/project/settings/import_export_troubleshooting.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Import +group: Import and Integrate info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- @@ -10,10 +10,10 @@ If you have problems with [migrating projects using file exports](import_export. ## Troubleshooting commands -Finds information about the status of the import and further logs using the JID: +Finds information about the status of the import and further logs using the JID, +using the [Rails console](../../../administration/operations/rails_console.md): ```ruby -# Rails console Project.find_by_full_path('group/project').import_state.slice(:jid, :status, :last_error) > {"jid"=>"414dec93f941a593ea1a6894", "status"=>"finished", "last_error"=>nil} ``` @@ -35,6 +35,27 @@ Review [issue 276930](https://gitlab.com/gitlab-org/gitlab/-/issues/276930), and - Ensure shared runners are enabled in both the source and destination projects. - Disable shared runners on the parent group when you import the project. +## Users missing from imported project + +If users aren't imported with imported projects, see the [preserving user contributions](import_export.md#preserving-user-contributions) requirements. + +A common reason for missing users is that the [public email setting](../../profile/index.md#set-your-public-email) isn't configured for users. +To resolve this issue, ask users to configure this setting using the GitLab UI. + +If there are too many users for manual configuration to be feasible, +you can set all user profiles to use a public email address using the +[Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): + +```ruby +User.where("public_email IS NULL OR public_email = '' ").find_each do |u| + next if u.bot? + + puts "Setting #{u.username}'s currently empty public email to #{u.email}…" + u.public_email = u.email + u.save! +end +``` + ## Import workarounds for large repositories [Maximum import size limitations](import_export.md#import-a-project-and-its-data) @@ -48,41 +69,41 @@ reduce the repository size for another import attempt: 1. Create a temporary working directory from the export: - ```shell - EXPORT=<filename-without-extension> + ```shell + EXPORT=<filename-without-extension> - mkdir "$EXPORT" - tar -xf "$EXPORT".tar.gz --directory="$EXPORT"/ - cd "$EXPORT"/ - git clone project.bundle + mkdir "$EXPORT" + tar -xf "$EXPORT".tar.gz --directory="$EXPORT"/ + cd "$EXPORT"/ + git clone project.bundle - # Prevent interference with recreating an importable file later - mv project.bundle ../"$EXPORT"-original.bundle - mv ../"$EXPORT".tar.gz ../"$EXPORT"-original.tar.gz + # Prevent interference with recreating an importable file later + mv project.bundle ../"$EXPORT"-original.bundle + mv ../"$EXPORT".tar.gz ../"$EXPORT"-original.tar.gz - git switch --create smaller-tmp-main - ``` + git switch --create smaller-tmp-main + ``` 1. To reduce the repository size, work on this `smaller-tmp-main` branch: [identify and remove large files](../repository/reducing_the_repo_size_using_git.md) or [interactively rebase and fixup](../../../topics/git/git_rebase.md#interactive-rebase) to reduce the number of commits. - ```shell - # Reduce the .git/objects/pack/ file size - cd project - git reflog expire --expire=now --all - git gc --prune=now --aggressive - - # Prepare recreating an importable file - git bundle create ../project.bundle <default-branch-name> - cd .. - mv project/ ../"$EXPORT"-project - cd .. - - # Recreate an importable file - tar -czf "$EXPORT"-smaller.tar.gz --directory="$EXPORT"/ . - ``` + ```shell + # Reduce the .git/objects/pack/ file size + cd project + git reflog expire --expire=now --all + git gc --prune=now --aggressive + + # Prepare recreating an importable file + git bundle create ../project.bundle <default-branch-name> + cd .. + mv project/ ../"$EXPORT"-project + cd .. + + # Recreate an importable file + tar -czf "$EXPORT"-smaller.tar.gz --directory="$EXPORT"/ . + ``` 1. Import this new, smaller file into GitLab. 1. In a full clone of the original repository, @@ -153,12 +174,12 @@ Rather than attempting to push all changes at once, this workaround: You usually export a project through [the web interface](import_export.md#export-a-project-and-its-data) or through [the API](../../../api/project_import_export.md). Exporting using these methods can sometimes fail without giving enough information to troubleshoot. In these cases, -[open a rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) and loop through +[open a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) and loop through [all the defined exporters](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/projects/import_export/export_service.rb). Execute each line individually, rather than pasting the entire block at once, so you can see any errors each command returns. -```shell +```ruby # User needs to have permission to export u = User.find_by_username('someuser') p = Project.find_by_full_path('some/project') @@ -265,12 +286,12 @@ Marked stuck import jobs as failed. JIDs: xyz | Problem | Possible solutions | | -------- | -------- | | [Slow JSON](https://gitlab.com/gitlab-org/gitlab/-/issues/25251) loading/dumping models from the database | [split the worker](https://gitlab.com/gitlab-org/gitlab/-/issues/25252) | -| | Batch export -| | Optimize SQL -| | Move away from `ActiveRecord` callbacks (difficult) -| High memory usage (see also some [analysis](https://gitlab.com/gitlab-org/gitlab/-/issues/18857) | DB Commit sweet spot that uses less memory | +| | Batch export | +| | Optimize SQL | +| | Move away from `ActiveRecord` callbacks (difficult) | +| High memory usage (see also some [analysis](https://gitlab.com/gitlab-org/gitlab/-/issues/18857)) | DB Commit sweet spot that uses less memory | | | [Netflix Fast JSON API](https://github.com/Netflix/fast_jsonapi) may help | -| | Batch reading/writing to disk and any SQL +| | Batch reading/writing to disk and any SQL | ### Temporary solutions diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index ed4eea56514..f89c2a1eaaa 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Organization +stage: Data Stores +group: Tenant Scale info: 'To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments' type: reference, index, howto --- @@ -75,28 +75,28 @@ To configure visibility, features, and permissions for a project: Use the toggles to enable or disable features in the project. -| Option | More access limit options | Description | -| :------------------------------- | :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Issues** | ✓ | Activates the GitLab issues tracker. | -| **Repository** | ✓ | Enables [repository](../repository/index.md) functionality | -| **Merge requests** | ✓ | Enables [merge request](../merge_requests/index.md) functionality; also see [Merge request settings](#configure-merge-request-settings-for-a-project). | -| **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality. | -| **Git Large File Storage (LFS)** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs). | -| **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. | -| **CI/CD** | ✓ | Enables [CI/CD](../../../ci/index.md) functionality. | -| **Container Registry** | | Activates a [registry](../../packages/container_registry/index.md) for your Docker images. | -| **Analytics** | ✓ | Enables [analytics](../../analytics/index.md). | -| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md). | -| **Security & Compliance** | ✓ | Control access to [security features](../../application_security/index.md). | -| **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/index.md). | -| **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md). | -| **Pages** | ✓ | Allows you to [publish static websites](../pages/index.md). | -| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | -| **Releases** | ✓ | Control access to [Releases](../releases/index.md). | -| **Environments** | ✓ | Control access to [Environments and Deployments](../../../ci/environments/index.md). | -| **Feature flags** | ✓ | Control access to [Feature Flags](../../../operations/feature_flags.md). | -| **Monitor** | ✓ | Control access to [Monitor](../../../operations/index.md) features. | -| **Infrastructure** | ✓ | Control access to [Infrastructure](../../infrastructure/index.md) features. | +| Option | More access limit options | Description +| :------------------------------- | :------------------------ | :---------- | +| **Issues** | **{check-circle}** Yes | Activates the GitLab issues tracker. +| **Repository** | **{check-circle}** Yes | Enables [repository](../repository/index.md) functionality. +| **Merge requests** | **{check-circle}** Yes | Enables [merge request](../merge_requests/index.md) functionality; also see [Merge request settings](#configure-merge-request-settings-for-a-project). +| **Forks** | **{check-circle}** Yes | Enables [forking](../repository/forking_workflow.md) functionality. +| **Git Large File Storage (LFS)** | **{dotted-circle}** No | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs). +| **Packages** | **{dotted-circle}** No | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. +| **CI/CD** | **{check-circle}** Yes | Enables [CI/CD](../../../ci/index.md) functionality. +| **Container Registry** | **{dotted-circle}** No | Activates a [registry](../../packages/container_registry/index.md) for your Docker images. +| **Analytics** | **{check-circle}** Yes | Enables [analytics](../../analytics/index.md). +| **Requirements** | **{check-circle}** Yes | Control access to [Requirements Management](../requirements/index.md). +| **Security and Compliance** | **{check-circle}** Yes | Control access to [security features](../../application_security/index.md). +| **Wiki** | **{check-circle}** Yes | Enables a separate system for [documentation](../wiki/index.md). +| **Snippets** | **{check-circle}** Yes | Enables [sharing of code and text](../../snippets.md). +| **Pages** | **{check-circle}** Yes | Allows you to [publish static websites](../pages/index.md). +| **Metrics Dashboard** | **{check-circle}** Yes | Control access to [metrics dashboard](../integrations/prometheus.md). +| **Releases** | **{check-circle}** Yes | Control access to [Releases](../releases/index.md). +| **Environments** | **{check-circle}** Yes | Control access to [Environments and Deployments](../../../ci/environments/index.md). +| **Feature flags** | **{check-circle}** Yes | Control access to [Feature flags](../../../operations/feature_flags.md). +| **Monitor** | **{check-circle}** Yes | Control access to [Monitor](../../../operations/index.md) features. +| **Infrastructure** | **{check-circle}** Yes | Control access to [Infrastructure](../../infrastructure/index.md) features. When you disable a feature, the following additional features are also disabled: @@ -162,6 +162,7 @@ Configure your project's merge request settings: - Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). - 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. +- Enable [Suggested Reviewers](../merge_requests/reviews/index.md#suggested-reviewers). ## Service Desk @@ -174,7 +175,7 @@ Learn how to [export a project](import_export.md#import-a-project-and-its-data) ## Advanced project settings Use the advanced settings to archive, rename, transfer, -remove a fork relationship, or delete a project. +[remove a fork relationship](../repository/forking_workflow.md#unlink-a-fork), or delete a project. ### Archive a project @@ -347,24 +348,6 @@ To restore a project marked for deletion: 1. Navigate to your project, and select **Settings > General > Advanced**. 1. In the Restore project section, select **Restore project**. -## Remove a fork relationship - -Prerequisites: - -- You must be a project owner to remove a fork relationship. - -WARNING: -If you remove a fork relationship, you can't send merge requests to the source. If anyone has forked your project, their fork also loses the relationship. -To restore the fork relationship, [use the API](../../../api/projects.md#create-a-forked-fromto-relation-between-existing-projects). - -To remove a fork relationship: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Advanced**. -1. In the **Remove fork relationship** section, select **Remove fork relationship**. -1. To confirm, enter the project path and select **Confirm**. - ## Monitor settings ### Alerts @@ -375,7 +358,7 @@ Configure [alert integrations](../../../operations/incident_management/integrati #### Alert integration -Automatically [create](../../../operations/metrics/alerts.md#trigger-actions-from-alerts), [notify on](../../../operations/incident_management/paging.md#email-notifications-for-alerts), and [resolve](../../../operations/incident_management/manage_incidents.md#automatically-close-incidents-via-recovery-alerts) incidents based on GitLab alerts. +Automatically [create](../../../operations/incident_management/alerts.md#trigger-actions-from-alerts), [notify on](../../../operations/incident_management/paging.md#email-notifications-for-alerts), and [resolve](../../../operations/incident_management/manage_incidents.md#automatically-close-incidents-via-recovery-alerts) incidents based on GitLab alerts. #### PagerDuty integration @@ -398,16 +381,6 @@ to enable the syncing of public Issues to a [deployed status page](../../../oper When working with project settings, you might encounter the following issues, or require alternate methods to complete specific tasks. -### Remove a fork relationship through console - -If removing the fork through the UI or API is not working, you can attempt the fork relationship removal in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). - -```ruby -p = Project.find_by_full_path('<project_path>') -u = User.find_by_username('<username>') -Projects::UnlinkForkService.new(p, u).execute -``` - ### Transfer a project through console If transferring a project through the UI or API is not working, you can attempt the transfer in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index f9218a228ca..178500093e2 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -28,16 +28,12 @@ and [personal access tokens](../../profile/personal_access_tokens.md). In self-managed instances, project access tokens are subject to the same [maximum lifetime limits](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) as personal access tokens if the limit is set. WARNING: -The ability to create project access tokens without expiry was -[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369122) in GitLab 15.4 and is planned for removal in GitLab -16.0. When this ability is removed, existing project access tokens without an expiry are planned to have an expiry added. -The automatic adding of an expiry occurs on GitLab.com during the 16.0 milestone. The automatic adding of an expiry -occurs on self-managed instances when they are upgraded to GitLab 16.0. This change is a breaking change. +The ability to create project access tokens without expiry was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369122) in GitLab 15.4 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/392855) in GitLab 16.0. In GitLab 16.0 and later, existing project access tokens without an expiry date are automatically given an expiry date of 365 days later than the current date. The automatic adding of an expiry date occurs on GitLab.com during the 16.0 milestone. The automatic adding of an expiry date occurs on self-managed instances when they are upgraded to GitLab 16.0. This change is a breaking change. You can use project access tokens: -- On GitLab SaaS if you have the Premium license tier or higher. Project 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: +- On GitLab SaaS: If you have the Premium or Ultimate license tier. Project 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 @@ -48,32 +44,33 @@ You cannot use project access tokens to create other group, project, or personal 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: -Project access tokens are not FIPS compliant and creation and use are disabled when [FIPS mode](../../../development/fips_compliance.md) is enabled. - ## Create a project access token > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89114) in GitLab 15.1, Owners can select Owner role for project access tokens. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348660) in GitLab 15.3, default expiration of 30 days and default role of Guest is populated in the UI. +> - Ability to create non-expiring project access tokens [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/392855) in GitLab 16.0. + +WARNING: +Project access tokens are treated as [internal users](../../../development/internal_users.md). +If an internal user creates a project access token, that token is able to access +all projects that have visibility level set to [Internal](../../public_access.md). To create a project access token: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Access Tokens**. 1. Enter a name. The token name is visible to any user with permissions to view the project. -1. Optional. Enter an expiry date for the token. The token expires on that date at midnight UTC. An instance-wide [maximum lifetime](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) setting can limit the maximum allowable lifetime in self-managed instances. - +1. Enter an expiry date for the token. + - The token expires on that date at midnight UTC. + - If you do not enter an expiry date, the expiry date is automatically set to 365 days later than the current date. + - By default, this date can be a maximum of 365 days later than the current date. + - An instance-wide [maximum lifetime](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) setting can limit the maximum allowable lifetime in self-managed instances. 1. Select a role for the token. 1. Select the [desired scopes](#scopes-for-a-project-access-token). 1. Select **Create project access token**. 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. -WARNING: -Project access tokens are treated as [internal users](../../../development/internal_users.md). -If an internal user creates a project access token, that token is able to access -all projects that have visibility level set to [Internal](../../public_access.md). - ## Revoke a project access token To revoke a project access token: @@ -121,12 +118,8 @@ The bot users for projects have [permissions](../../permissions.md#project-membe 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@noreply.{Gitlab.config.gitlab.host}`. For example, `project123_bot@noreply.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}@noreply.{Gitlab.config.gitlab.host}`. - For example, `project123_bot1@noreply.example.com`. +- The username is set to `project_{project_id}_bot_{random_string}`. For example, `project_123_bot_4ffca233d8298ea1`. +- The email is set to `project_{project_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}`. For example, `project_123_bot_4ffca233d8298ea1@noreply.example.com`. API calls made with a project access token are associated with the corresponding bot user. @@ -143,3 +136,7 @@ When the project access token is [revoked](#revoke-a-project-access-token): - All records are moved to a system-wide user with the username [Ghost User](../../profile/account/delete_account.md#associated-records). See also [Bot users for groups](../../group/settings/group_access_tokens.md#bot-users-for-groups). + +## Token availability + +Project access tokens are only available in paid subscriptions, and not available in trial subscriptions. For more information, see the ["What is included" section of the GitLab Trial FAQ](https://about.gitlab.com/free-trial/#what-is-included-in-my-free-trial-what-is-excluded). diff --git a/doc/user/project/system_notes.md b/doc/user/project/system_notes.md new file mode 100644 index 00000000000..1eee4364d95 --- /dev/null +++ b/doc/user/project/system_notes.md @@ -0,0 +1,56 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# System notes **(FREE)** + +System notes are short descriptions that help you understand the history of events +that occur during the life cycle of a GitLab object, such as: + +- [Alerts](../../operations/incident_management/alerts.md). +- [Designs](issues/design_management.md). +- [Issues](issues/index.md). +- [Merge requests](merge_requests/index.md). +- [Objectives and key results](../okrs.md) (OKRs). +- [Tasks](../tasks.md). + +GitLab logs information about events triggered by Git or the GitLab application +in system notes. System notes use the format `<Author> <action> <time ago>`. + +## Show or filter system notes + +By default, system notes do not display. When displayed, they are shown oldest first. +If you change the filter or sort options, your selection is remembered across sections. +The filtering options are: + +- **Show all activity** displays both comments and history. +- **Show comments only** hides system notes. +- **Show history only** hides user comments. + +### On an epic + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Epics** (**{epic}**). +1. Identify your desired epic, and select its title. +1. Go to the **Activity** section. +1. For **Sort or filter**, select **Show all activity**. + +### On an issue + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues** and find your issue. +1. Go to **Activity**. +1. For **Sort or filter**, select **Show all activity**. + +### On a merge request + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find your merge request. +1. Go to **Activity**. +1. For **Sort or filter**, select **Show all activity**. + +## Related topics + +- [Notes API](../../api/notes.md) diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index d5f0b7e6180..bd935db6f02 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -1,6 +1,5 @@ --- type: reference -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/time_tracking.html' stage: Plan group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments diff --git a/doc/user/project/web_ide/img/admin_live_preview_v13_0.png b/doc/user/project/web_ide/img/admin_live_preview_v13_0.png Binary files differdeleted file mode 100644 index 90129d240bc..00000000000 --- a/doc/user/project/web_ide/img/admin_live_preview_v13_0.png +++ /dev/null diff --git a/doc/user/project/web_ide/img/commit_changes_v13_11.png b/doc/user/project/web_ide/img/commit_changes_v13_11.png Binary files differdeleted file mode 100644 index 6cd270a6112..00000000000 --- a/doc/user/project/web_ide/img/commit_changes_v13_11.png +++ /dev/null diff --git a/doc/user/project/web_ide/img/dark_theme_v13_0.png b/doc/user/project/web_ide/img/dark_theme_v13_0.png Binary files differdeleted file mode 100644 index 020578a9444..00000000000 --- a/doc/user/project/web_ide/img/dark_theme_v13_0.png +++ /dev/null diff --git a/doc/user/project/web_ide_beta/img/fuzzy_finder_v15_7.png b/doc/user/project/web_ide/img/fuzzy_finder_v15_7.png Binary files differindex 66ebae15e98..66ebae15e98 100644 --- a/doc/user/project/web_ide_beta/img/fuzzy_finder_v15_7.png +++ b/doc/user/project/web_ide/img/fuzzy_finder_v15_7.png diff --git a/doc/user/project/web_ide/img/live_preview_v13_0.png b/doc/user/project/web_ide/img/live_preview_v13_0.png Binary files differdeleted file mode 100644 index f701e137a6b..00000000000 --- a/doc/user/project/web_ide/img/live_preview_v13_0.png +++ /dev/null diff --git a/doc/user/project/web_ide/img/solarized_dark_theme_v13_1.png b/doc/user/project/web_ide/img/solarized_dark_theme_v13_1.png Binary files differdeleted file mode 100644 index 8eca352a4d0..00000000000 --- a/doc/user/project/web_ide/img/solarized_dark_theme_v13_1.png +++ /dev/null diff --git a/doc/user/project/web_ide/img/terminal_status.png b/doc/user/project/web_ide/img/terminal_status.png Binary files differdeleted file mode 100644 index 91c341a9854..00000000000 --- a/doc/user/project/web_ide/img/terminal_status.png +++ /dev/null diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 5e9f648daba..bb1609a74e5 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -1,472 +1,205 @@ --- stage: Create -group: Editor +group: IDE info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web IDE **(FREE)** -The Web IDE is an advanced editor with commit staging. -You can use the Web IDE to make changes to multiple files directly from the -GitLab UI. For a more basic implementation, see [Web Editor](../repository/web_editor.md). - -NOTE: -The Web IDE is being updated to use VS Code. For details, -see [Web IDE Beta](../web_ide_beta/index.md). - -## Open the Web IDE - -Use the <kbd>.</kbd> [keyboard shortcut](../../shortcuts.md) to open the Web IDE. -You can also open the Web IDE when viewing a file, from the repository file list, -and from merge requests: - -### When viewing a file or the repository file list - - 1. In the upper right corner of the page, select **Open in Web IDE** if it is visible. - 1. If **Open in Web IDE** is not visible: - 1. Select the (**{chevron-lg-down}**) next to **Edit** or **Gitpod**, depending on your configuration. - 1. Select **Open in Web IDE** from the list to display it as the editing option. - 1. Select **Open in Web IDE** to open the editor. - -### When viewing a merge request - - 1. Go to your merge request. - 1. In the upper right corner, select **Code > Open in Web IDE**. - -## File finder - -The file finder allows you to quickly open files in the current branch by -searching for fragments of the file path. The file finder is launched using the keyboard shortcut -<kbd>Command</kbd>+<kbd>p</kbd>, <kbd>Control</kbd>+<kbd>p</kbd>, or <kbd>t</kbd> -(when editor is not in focus). Type the filename or file path fragments to -start seeing results. - -## Command palette +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115741) in GitLab 15.11. -You can see all available commands for manipulating editor content by pressing -the <kbd>F1</kbd> key when the editor is in focus. After that, the editor displays -a complete list of available commands for -manipulating editor content. The editor supports commands for multi-cursor -editing, code block folding, commenting, searching and replacing, navigating -editor warnings and suggestions, and more. +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. -Some commands have a keyboard shortcut assigned to them. The command palette -displays this shortcut next to each command. You can use this shortcut to invoke -the command without having to select it in the command palette. - -For a full list of keyboard shortcuts in the Web IDE, refer to the -[Keyboard shortcuts](../../shortcuts.md#web-ide) list. - -## Syntax highlighting - -As expected from an IDE, syntax highlighting for many languages in -the Web IDE makes your direct editing even easier. - -The Web IDE currently provides: - -- Basic syntax colorization for a variety of programming, scripting and markup - languages such as XML, PHP, C#, C++, Markdown, Java, VB, Batch, Python, Ruby, - and Objective-C. -- IntelliSense and validation support (displaying errors and warnings, providing - smart completions, formatting, and outlining) for some languages. For example: - TypeScript, JavaScript, CSS, LESS, SCSS, JSON, and HTML. - -Because the Web IDE is based on the [Monaco Editor](https://microsoft.github.io/monaco-editor/), -you can find a more complete list of supported languages in the -[Monaco languages](https://github.com/Microsoft/monaco-languages) repository. Under the hood, -Monaco uses the [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for syntax highlighting. +The Web IDE is an advanced editor with commit staging. +You can use the Web IDE to make changes to multiple files directly from the GitLab UI. +For a more basic implementation, see [Web Editor](../repository/web_editor.md). -If you are missing Syntax Highlighting support for any language, we prepared a short guide on how to [add support for a missing language Syntax Highlighting.](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/ide/lib/languages/README.md) +To pair the Web IDE with a remote development environment, see [remote development](../remote_development/index.md). -### Themes +## Use the Web IDE -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in GitLab 13.0. -> - Full Solarized Dark Theme [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219228) in GitLab 13.1. -> - Full [Solarized Light](https://gitlab.com/gitlab-org/gitlab/-/issues/221035) and [Monokai](https://gitlab.com/gitlab-org/gitlab/-/issues/221034) Themes introduced in GitLab 13.6. +To open the Web IDE from the GitLab UI: -All the themes GitLab supports for syntax highlighting are applied to the entire Web IDE screen. -You can pick a theme from your [profile preferences](../../profile/preferences.md). +1. On the top bar, select **Main menu > Projects** and find your project. +1. Use the <kbd>.</kbd> keyboard shortcut. -| Solarized Dark Theme | Dark Theme | -|-------------------------------------------------------------|-----------------------------------------| -|  |  | +You can also open the Web IDE from: -## Link to specific lines +- A file +- The repository file list +- A merge request -The Web IDE and the [Web Editor](../repository/web_editor.md) share the -same core features. To link to specific lines in the Web IDE, see -[Web Editor](../repository/web_editor.md#link-to-specific-lines). +### From a file or the repository file list -## Schema based validation +To open the Web IDE from a file or the repository file list: -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) validation based on predefined schemas in GitLab 13.2 [with a flag](../../../administration/feature_flags.md) named `schema_linting`. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104399) in GitLab 15.7. -> - On self-managed GitLab [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107488) in GitLab 15.8. +- In the upper-right corner of the page, select **Open in Web IDE**. -The Web IDE provides validation support for certain JSON and YAML files using schemas -based on the [JSON Schema Store](https://www.schemastore.org/json/). +If **Open in Web IDE** is not visible: -### Predefined schemas +1. Next to **Edit** or **Gitpod**, select the down arrow (**{chevron-lg-down}**). +1. From the dropdown list, select **Open in Web IDE**. +1. Select **Open in Web IDE**. -The Web IDE has validation for certain files built in. This feature is only supported for -the `*.gitlab-ci.yml` files. +### From a merge request -### Custom schemas **(PREMIUM)** +To open the Web IDE from a merge request: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/226982) in GitLab 13.4. +1. Go to your merge request. +1. In the upper-right corner, select **Code > Open in Web IDE**. -The Web IDE also allows you to define custom schemas for certain JSON/YAML files in your project. -You can do so by defining a `schemas` entry in the `.gitlab/.gitlab-webide.yml` file inside the -repository's root. Here is an example configuration: +The Web IDE opens new and modified files in separate tabs and displays changes side by side with the original source. +To optimize loading time, only the top 10 files (by number of lines changed) are opened automatically. -```yaml -schemas: - - uri: https://json.schemastore.org/package - match: - - package.json - - uri: https://somewebsite.com/first/raw/url - match: - - data/release_posts/unreleased/*.{yml,yaml} - - uri: https://somewebsite.com/second/raw/url - match: - - "*.meta.json" -``` +In the file tree, any new or modified file in the merge request is indicated by an icon next to the filename. +To view changes to a file, right-click the filename and select **Compare with merge request base**. -Each schema entry supports two properties: +## Open a file in the Web IDE -- `uri`: Provide an absolute URL for the schema definition file here. - The schema from this URL is loaded when a matching file is open. -- `match`: A list of matching paths or glob expressions. If a schema matches a - particular path pattern, it is applied to that file. Enclose the pattern - in quotes if it begins with an asterisk (`*`), it's be applied to that file. - If a pattern begins with an asterisk (`*`), enclose it in quotation marks. - Otherwise, the configuration file is not valid YAML. +To open any file by its name: -## Configure the Web IDE +1. Press <kbd>Command</kbd>+<kbd>P</kbd>. +1. Enter the name of your file. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in GitLab 13.1. + -The Web IDE supports configuration of certain editor settings by using -[`.editorconfig` files](https://editorconfig.org/). When opening a file, the -Web IDE looks for a file named `.editorconfig` in the current directory -and all parent directories. If a configuration file is found and has settings -that match the file's path, these settings are enforced on the opened file. +## Search across files -The Web IDE currently supports the following `.editorconfig` settings: +You can use the Web IDE to search all files in the opened folder. -- `indent_style` -- `indent_size` -- `end_of_line` -- `trim_trailing_whitespace` -- `tab_width` -- `insert_final_newline` +To search across files: -## Commit changes +1. Press <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>F</kbd>. +1. Enter your search term. -> - [Starting](https://gitlab.com/gitlab-org/gitlab/-/issues/33441) with GitLab 12.7, files are automatically staged. -> - In GitLab 12.9, support for staging files was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/196609) to prevent loss of unstaged data. All of your current changes must be committed or discarded. +In the Web IDE, only partial results from opened files are displayed. -After making your changes, select **Commit** on the bottom-left to -review the list of changed files. +## View a list of changed files -After you have finalized your changes, you can add a commit message, commit the -changes and directly create a merge request. In case you don't have write -access to the selected branch, you see a warning, but can still create -a new branch and start a merge request. +To view a list of files you changed in the Web IDE: -To discard a change in a particular file, select **Discard changes** on that -file in the changes tab. To discard all the changes, select the trash icon in the -upper-right corner of the changes sidebar. +- On the activity bar on the left, select **Source Control**, + or press <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>G</kbd>. - +Your `CHANGES`, `STAGED CHANGES`, and `MERGE CHANGES` are displayed. +For more information, see the [VS Code documentation](https://code.visualstudio.com/docs/sourcecontrol/overview#_commit). -## Reviewing changes +## Upload a new file -Before you commit your changes, you can compare them with the previous commit -by switching to the review mode or selecting the file from the list of changes. +To upload a new file and add it to the Git repository: -An additional review mode is available when you open a merge request, which -shows you a preview of the merge request diff if you commit your changes. +1. In the **Explorer** file tree, navigate to the directory where you want to upload the file. +1. Optional. If the directory does not exist yet, select the directory path where you want to have a new directory and either: + - Right-click on the directory path, and select **New Folder...**. You can create a nested directory path with the `/` separator, for example `parentdir/subdir1/subdir2`. + - In the **Explorer** panel, in the upper-right corner, select the new folder (**{folder-new}**) icon. +1. Enter the name of the new directory, and press <kbd>Enter/Return</kbd> to create it. +1. Right-click on the directory path and select `Upload...`. +1. Select the file you want to upload, then select `Open`. You can select and add multiple files at once. -## View CI job logs +The file is uploaded and automatically added as a new file to the Git repository. -You can use the Web IDE to quickly fix failing tests by opening -the branch or merge request in the Web IDE and opening the logs of the failed -job. You can access the status of all jobs for the most recent pipeline and job -traces for the current commit by selecting the **Pipelines** button in the top -right. +## Switch branches -The pipeline status is also shown at all times in the status bar in the bottom -left. +The Web IDE uses the currently selected branch by default. +To switch branches in the Web IDE: -## Switching merge requests +1. On the status bar, in the lower-left corner, select the current branch name. +1. In the search box, start typing the branch name. +1. From the dropdown list, select the branch. -To switch between your authored and assigned merge requests, select the -dropdown list in the top of the sidebar to open a list of merge requests. You must commit or discard all your changes before switching to a different merge -request. +## Create a branch -## Switching branches +To create a branch from the current branch in the Web IDE: -To switch between branches of the current project repository, select the dropdown list -in the top of the sidebar to open a list of branches. -You must commit or discard all your changes before switching to a -different branch. +1. On the status bar, in the lower-left corner, select the current branch name. +1. From the dropdown list, select **Create new branch...**. +1. Enter the branch name. +1. Press <kbd>Enter</kbd>. -## Markdown editing +If you don't have write access to the repository, **Create new branch...** is not visible. -> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in GitLab 13.1. -> - Side-by-side Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68274) in GitLab 14.3. - -To edit Markdown files in the Web IDE: +## Commit changes -1. Go to your repository, and navigate to the Markdown page you want to edit. -1. Select **Open in Web IDE**, and GitLab loads the page in a tab in the editor. -1. Make your changes to the file. GitLab supports [GitLab Flavored Markdown (GLFM)](../../markdown.md). -1. When your changes are complete, select **Commit** in the left sidebar. -1. Add a commit message, select the branch you want to commit to, and select **Commit**. +To commit changes in the Web IDE: -When editing, you can upload local images by pasting them directly in the Markdown file. -The image is uploaded to the same directory and is named `image.png` by default. -If another file already exists with the same name, a numeric suffix is automatically -added to the filename. +1. On the activity bar on the left, select **Source Control**, + or press <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>G</kbd>. +1. Enter your commit message. +1. Select **Commit & Push**. +1. Commit to the current branch, or create a new branch. -There are two ways to preview Markdown content in the Web IDE: +## Use the command palette -1. At the top of the file's tab, select **Preview Markdown** to preview the formatting - in your file. You can't edit the file in this view. - 1. To add more changes to the file, select **Edit**. -1. Right-click or use the keyboard shortcut `Command/Control + Shift + P` and - select **Preview Markdown** to toggle a live Markdown preview panel. +In the Web IDE, you can access many commands through the command palette. +To open the command palette and run a command in the Web IDE: -<!--- start_remove The following content will be removed on remove_date: '2023-02-01' --> +1. Press <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd>. +1. In the search box, start typing the command name. +1. From the dropdown list, select the command. -## Live Preview (removed) +## Edit settings -WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108627) in GitLab 15.8 -and is planned for removal in 15.9. This change is a breaking change. +You can use the settings editor to view and modify your user and workspace settings. +To open the settings editor in the Web IDE: -> [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/213853) from _Client Side Evaluation_ to _Live Preview_ in GitLab 13.0. +- On the top menu bar, select **File > Preferences > Settings**, + or press <kbd>Command</kbd>+<kbd>,</kbd>. -You can use the Web IDE to preview JavaScript projects right in the browser. -This feature uses CodeSandbox to compile and bundle the JavaScript used to -preview the web application. +In the settings editor, you can search for the settings you want to modify. - +## Edit keyboard shortcuts -Additionally, for public projects an **Open in CodeSandbox** button is available -to transfer the contents of the project into a public CodeSandbox project to -quickly share your project with others. +You can use the keyboard shortcuts editor to view and modify the default keybindings for all available commands. +To open the keyboard shortcuts editor in the Web IDE: -### Enable Live Preview +- On the top menu bar, select **File > Preferences > Keyboard Shortcuts**, + or press <kbd>Command</kbd>+<kbd>K</kbd> then <kbd>Command</kbd>+<kbd>S</kbd>. -With Live Preview enabled, you can preview projects with a `package.json` file and -a `main` entry point inside the Web IDE. +In the keyboard shortcuts editor, you can search for: -Live Preview is enabled for all projects on GitLab.com. If you are an administrator -of a self-managed GitLab instance, and you want to enable Live Preview: +- The keybindings you want to change +- The commands you want to add or remove keybindings for -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. -1. Scroll to **Web IDE** and select **Expand**: -  -1. Select **Enable Live Preview** and select **Save changes**. +Keybindings are based on your keyboard layout. If you change your keyboard layout, existing keybindings are updated automatically. -[In GitLab 12.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/268288), -third-party assets and libraries required for Live Preview are hosted at -`https://sandbox-prod.gitlab-static.net` when it is enabled. However, some libraries -are still served from other third-party services, which may or may not be desirable -in your environment. +## Change themes -An example `package.json`: +You can choose between different themes for the Web IDE. The default theme for the Web IDE is **GitLab Dark**. -```json -{ - "main": "index.js", - "dependencies": { - "vue": "latest" - } -} -``` +To change the Web IDE theme: -<!--- end_remove --> +1. On the top menu bar, select **File > Preferences > Theme > Color Theme**, + or press <kbd>Command</kbd>+<kbd>K</kbd> then <kbd>Command</kbd>+<kbd>T</kbd>. +1. From the dropdown list, preview the themes with the arrow keys. +1. Select a theme. -## Interactive Web Terminals for the Web IDE +The active color theme is stored in the [user settings](#edit-settings). -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) from GitLab Ultimate to GitLab Free in 13.1. +<!-- ## Privacy and data collection for extensions -WARNING: -Interactive Web Terminals for the Web IDE is currently in [**Beta**](../../../policy/alpha-beta-support.md#beta-features). -GitLab.com shared runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab/-/issues/24674), -so you must use your own private runner to make use of this feature. +The Web IDE Extension Marketplace is based on Open VSX. Open VSX does not collect any +data about you or your activities on the platform. -[Interactive Web Terminals](../../../ci/interactive_web_terminal/index.md) -give the project [Maintainers](../../permissions.md#project-members-permissions) -user access to a terminal to interact with the runner directly from -GitLab, including through the Web IDE. +However, the privacy and data collection practices of extensions available on Open VSX can vary. +Some extensions might collect data to provide personalized recommendations or to improve the functionality. +Other extensions might collect data for analytics or advertising purposes. -### Runner configuration +To protect your privacy and data: -Some things must be configured in the runner for the interactive web terminal -to work: +- Carefully review the permissions requested by an extension before you install the extension. +- Keep your extensions up to date to ensure that any security or privacy vulnerabilities are addressed promptly. --> -- The runner needs to have - [`[session_server]` configured properly](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section). - This section requires at least a `session_timeout` value (which defaults to 1800 - seconds) and a `listen_address` value. If `advertise_address` is not defined, `listen_address` is used. -- If you are using a reverse proxy with your GitLab instance, web terminals must be - [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). +## Interactive web terminals for the Web IDE (Beta) -If you have the terminal open and the job has finished with its tasks, the -terminal blocks the job from finishing for the duration configured in -[`[session_server].session_timeout`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) -until you close the terminal window. - -NOTE: -Not all executors are -[supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). -The [File Sync](#file-syncing-to-web-terminal) feature is supported on Kubernetes runners only. - -### Web IDE configuration file - -To enable the Web IDE terminals you must create the file -`.gitlab/.gitlab-webide.yml` inside the repository's root. This -file is fairly similar to the [`.gitlab-ci.yml` file](../../../ci/yaml/index.md) -syntax but with some restrictions: - -- No global blocks (such as `before_script` or `after_script`) can be defined. -- Only one job named `terminal` can be added to this file. -- Only the keywords `image`, `services`, `tags`, `before_script`, `script`, and - `variables` are allowed to be used to configure the job. -- To connect to the interactive terminal, the `terminal` job must be still alive - and running, otherwise the terminal cannot connect to the job's session. - By default the `script` keyword has the value `sleep 60` to prevent - the job from ending and giving the Web IDE enough time to connect. This means - that, if you override the default `script` value, you have to add a command - which would keep the job running, like `sleep`. - -For example, with this configuration file: - -```yaml -terminal: - # This can be any image that has the necessary runtime environment for your project. - image: node:10-alpine - before_script: - - apk update - script: sleep 60 - variables: - RAILS_ENV: "test" - NODE_ENV: "test" -``` - -After the terminal starts, the console is displayed and you can access -the project repository files. - -When you use the `image` keyword, a container with the specified image is created. -If you use the [shell executor](https://docs.gitlab.com/runner/executors/shell.html) -or the [SSH executor](https://docs.gitlab.com/runner/executors/ssh.html), `image` has no effect. - -The terminal job is branch dependent. The configuration file used to trigger -and configure the terminal is the one in the selected branch of the Web IDE. -If no configuration file exists in a branch, an error message is displayed. - -### Running interactive terminals in the Web IDE - -If Interactive Terminals are available for the current user, the **Terminal** button is visible in the right sidebar of the Web IDE. Select this button to open -or close the terminal tab. - -After opening, the tab shows the **Start Web Terminal** button. This button may -be disabled if the environment is not configured correctly. If so, a status -message describes the issue. Here are some reasons why **Start Web Terminal** -may be disabled: - -- `.gitlab/.gitlab-webide.yml` does not exist or is set up incorrectly. -- No active private runners are available for the project. - -If active, selecting the **Start Web Terminal** button loads the terminal view -and start connecting to the runner's terminal. At any time, the **Terminal** tab -can be closed and reopened and the state of the terminal is not affected. - -When the terminal is started and is successfully connected to the runner, then the -runner's shell prompt appears in the terminal. From here, you can enter -commands executed in the runner's environment. This is similar -to running commands in a local terminal or through SSH. - -While the terminal is running, it can be stopped by selecting **Stop Terminal**. -This disconnects the terminal and stops the runner's terminal job. From here, -select **Restart Terminal** to start a new terminal session. - -### File syncing to web terminal - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5276) in GitLab 12.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211686) from GitLab Ultimate to GitLab Free in 13.1. - -File changes in the Web IDE can be synced to a running web terminal. -This enables users to test their code changes in a preconfigured terminal -environment. - -NOTE: -Only file changes in the Web IDE are synced to the terminal. -Changes made in the terminal are **not** synced to the Web IDE. -This feature is only available for Kubernetes runners. - -To enable file syncing to the web terminal, the `.gitlab/.gitlab-webide.yml` -file needs to have a `webide-file-sync` service configured. Here is an example -configuration for a Node JS project which uses this service: - -```yaml -terminal: - # This can be any image that has the necessary runtime environment for your project. - image: - name: node:10-alpine - services: - - name: registry.gitlab.com/gitlab-org/webide-file-sync:latest - alias: webide-file-sync - entrypoint: ["/bin/sh"] - command: ["-c", "sleep 5 && ./webide-file-sync -project-dir $CI_PROJECT_DIR"] - ports: - # The `webide-file-sync` executable defaults to port 3000. - - number: 3000 -``` - -- The `webide-file-sync` executable must start **after** the project - directory is available. This is why we must add `sleep 5` to the `command`. - See [this issue](https://gitlab.com/gitlab-org/webide-file-sync/-/issues/7) for - more information. -- `$CI_PROJECT_DIR` is a - [predefined CI/CD variable](../../../ci/variables/predefined_variables.md) - for GitLab Runners. This is where your project's repository resides. - -After you have configured the web terminal for file syncing, then when the web -terminal is started, a **Terminal** status is visible in the status bar. - - - -Changes made to your files via the Web IDE sync to the running terminal -when: - -- <kbd>Control</kbd> + <kbd>S</kbd> (or <kbd>Command</kbd> + <kbd>S</kbd> on Mac) - is pressed while editing a file. -- You select any area outside the file editor after editing a file. -- A file or folder is created, deleted, or renamed. - -### Known issues - -The Web IDE has a few limitations: - -- Interactive Terminals is in a beta phase and continues to be improved in upcoming releases. In the meantime, the user is limited to having only one - active terminal at a time. -- LFS files can be rendered and displayed but they cannot be updated and committed using the Web IDE. If an LFS file is modified and pushed to the repository, the LFS pointer in the repository is overwritten with the modified LFS file content. +When you set up a remote development server in the Web IDE, you can use interactive web terminals to: -### Troubleshooting +- Access a remote shell on the server. +- Interact with the server's file system and execute commands remotely. -- If the terminal's text is gray and unresponsive, then the terminal has stopped - and it can no longer be used. A stopped terminal can be restarted by selecting - **Restart Terminal**. -- If the terminal displays **Connection Failure**, then the terminal could not - connect to the runner. Try to stop and restart the terminal. If the - problem persists, double check your runner configuration. - -## Related topics +You cannot use interactive web terminals to interact with a runner. +However, you can use a terminal to install dependencies and compile and debug code. -- [Web IDE Beta](../web_ide_beta/index.md) +For more information about configuring a workspace that supports interactive web terminals, see [remote development](../remote_development/index.md). diff --git a/doc/user/project/web_ide_beta/index.md b/doc/user/project/web_ide_beta/index.md index fe110baf578..a4c733be376 100644 --- a/doc/user/project/web_ide_beta/index.md +++ b/doc/user/project/web_ide_beta/index.md @@ -1,106 +1,11 @@ --- -stage: Create -group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: '../web_ide/index.md' +remove_date: '2023-08-22' --- -# Web IDE Beta **(FREE)** +This document was moved to [another location](../web_ide/index.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. - -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 `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. - -As announced in [this blog post](https://about.gitlab.com/blog/2022/05/23/the-future-of-the-gitlab-web-ide/), -the current implementation of the [Web IDE](../web_ide/index.md) is being replaced -with an implementation powered by Visual Studio Code. This effort is still under -development. For updates, see [this epic](https://gitlab.com/groups/gitlab-org/-/epics/7683). - -To pair the Web IDE Beta with a Remote Development environment, see [Remote Development](../remote_development/index.md). - -## Enable the Web IDE Beta - -To use the Web IDE Beta on a self-managed GitLab instance, -ensure that the `vscode_web_ide` feature flag -[is enabled](../../../administration/feature_flags.md). - -On GitLab.com, this feature is available by default. However, you can -[stop using it if you choose](#stop-using-the-web-ide-beta). - -## Use the Web IDE Beta - -To open the Web IDE Beta from anywhere in the UI: - -- Use the <kbd>.</kbd> [keyboard shortcut](../../shortcuts.md). - -You can also open the Web IDE Beta when viewing a file, the repository file list, -or a merge request. - -### Use when viewing a file or the repository file list - -To open the Web IDE Beta from a file or the repository file list: - -- In the upper right of the page, select **Open in Web IDE**. - -If **Open in Web IDE** is not visible: - -1. Next to **Edit** or **Gitpod**, select the down arrow (**{chevron-lg-down}**). -1. From the list, select **Open in Web IDE**. -1. Select **Open in Web IDE**. - -### Use when viewing a merge request - -To open the Web IDE Beta from a merge request: - -1. Go to your merge request. -1. In the upper right corner, select **Code > Open in Web IDE**. - -## Open a file in the Web IDE Beta - -To open any file by its name: - -1. Press <kbd>Command</kbd>+<kbd>P</kbd>. -1. Enter the name of your file. - - - -## Search across files - -You can use VS Code to quickly search all files in the opened folder. - -To search across files: - -1. Press <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>F</kbd>. -1. Enter your search term. - -In the Web IDE Beta, only partial results from opened files are displayed. -Full file search is planned for a later date. - -## View a list of changed files - -To view a list of files you changed in the Web IDE Beta, -in the Activity Bar on the left, select **Source Control**. -Your `CHANGES`, `STAGED CHANGES`, and `MERGE CHANGES` are displayed. - -For details, see the [VS Code documentation](https://code.visualstudio.com/docs/sourcecontrol/overview#_commit). - -## Stop using the Web IDE Beta - -If you do not want to use the Web IDE Beta, you can change your personal preferences. - -1. On the top bar, in the upper-right corner, select your avatar. -1. Select **Preferences**. -1. In the **Web IDE** section, select the **Opt out of the Web IDE Beta** checkbox. -1. Select **Save changes**. - -## Known issues - -The [Web Terminal](../web_ide/index.md#interactive-web-terminals-for-the-web-ide) -and [Live Preview](../web_ide/index.md#live-preview-removed) are not available in the Web IDE Beta. - -These features might become available at a later date. - -## Related topics - -- [Remote Development](../remote_development/index.md) -- [Web IDE](../web_ide/index.md) +<!-- This redirect file can be deleted after <2023-08-22>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 53aaa41319b..9327ce53b3f 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -20,7 +20,7 @@ Group wikis are similar to [project wikis](index.md), with a few limitations: For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). Similar to project wikis, group members with at least the Developer role -and higher can edit group wikis. Group wiki repositories can be moved using the +can edit group wikis. Group wiki repositories can be moved using the [Group repository storage moves API](../../../api/group_repository_storage_moves.md). ## View a group wiki @@ -38,8 +38,8 @@ To access a group wiki: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247) in GitLab 13.9. Users with the Owner role in a group can -[import and export group wikis](../../group/settings/import_export.md) when importing -or exporting a group. +[import or export a group wiki](../../group/import/index.md#migrate-groups-by-uploading-an-export-file-deprecated) when they +import or export a group. Content created in a group wiki is not deleted when an account is downgraded or a GitLab trial ends. The group wiki data is exported whenever the group owner of @@ -48,8 +48,8 @@ the wiki is exported. To access the group wiki data from the export file if the feature is no longer available, you have to: -1. Extract the [export file tarball](../../group/settings/import_export.md) with - this command, replacing `FILENAME` with your file's name: +1. Extract the [export file tarball](../../group/import/index.md#migrate-groups-by-uploading-an-export-file-deprecated) + with this command, replacing `FILENAME` with your file's name: `tar -xvzf FILENAME.tar.gz` 1. Browse to the `repositories` directory. This directory contains a [Git bundle](https://git-scm.com/docs/git-bundle) with the extension `.wiki.bundle`. @@ -71,7 +71,7 @@ To open group settings: 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. 1. Scroll to **Wiki** and select one of these options: - - **Enabled**: Everyone who can access the group can access the wiki. + - **Enabled**: For public groups, everyone can access the wiki. For internal groups, only authenticated users can access the wiki. - **Private**: Only group members can access the wiki. - **Disabled**: The wiki isn't accessible, and cannot be downloaded. 1. Select **Save changes**. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index f01331ac784..eb13814f2ad 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index a0e6a78dfe2..69087791a3e 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Organization +stage: Data Stores +group: Tenant Scale info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- @@ -11,12 +11,9 @@ code are saved in projects, and most features are in the scope of projects. ## View projects -To view projects, on the top bar, select **Main menu > Projects > View all projects**. +To view all your projects, on the top bar, select **Main menu > Projects > View all projects**. -NOTE: -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. Then the tab is visible only to authenticated users. +To browse all public projects, select **Main menu > Explore > Projects**. ### Who can view the Projects page @@ -63,7 +60,7 @@ You can add a star to projects you use frequently to make them easier to find. To add a star to a project: 1. On the top bar, select **Main menu > Projects** and find your project. -1. In the upper right corner of the page, select **Star**. +1. In the upper-right corner of the page, select **Star**. ## View starred projects @@ -241,15 +238,15 @@ Configure Git to either: - Embed credentials in the request URL: - ```shell - git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" - ``` + ```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/" - ``` + ```shell + git config --global url."git@gitlab.example.com:".insteadOf "https://gitlab.example.com/" + ``` ### Disable Go module fetching for private projects @@ -263,8 +260,8 @@ the [environment variables](../../development/go_guide/dependencies.md#proxies): To disable fetching: 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`. + - 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`. @@ -291,8 +288,8 @@ To access the Geo secondary server with SSH: git config --global url."git@gitlab-secondary.example.com".insteadOf "http://gitlab.example.com" ``` - - For `gitlab.example.com`, use the primary site domain name. - - For `gitlab-secondary.example.com`, use the secondary site domain name. + - 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. @@ -331,7 +328,7 @@ download starts, the `insteadOf` configuration sends the traffic to the secondar - [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). +- [Fork a project](repository/forking_workflow.md#create-a-fork). - [Adjust project visibility and access levels](settings/index.md#configure-project-visibility-features-and-permissions). - [Limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names) |
