diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-04-07 18:18:20 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-04-07 18:18:20 +0000 |
| commit | 6d36b38d4d2901c244a0f8bdc4e36549ad821138 (patch) | |
| tree | 4df749e52aff6ac081521ccce3f0fa89d3e404af | |
| parent | a55ff7975e6c763e10127d22df4ba9c32ee2838f (diff) | |
| download | gitlab-ce-6d36b38d4d2901c244a0f8bdc4e36549ad821138.tar.gz | |
Add latest changes from gitlab-org/gitlab@master
25 files changed, 1052 insertions, 788 deletions
diff --git a/.rubocop.yml b/.rubocop.yml index 9fcb77fb7c2..12eee5702bc 100644 --- a/.rubocop.yml +++ b/.rubocop.yml @@ -454,6 +454,7 @@ Gitlab/RSpec/AvoidSetup: Enabled: true Include: - 'ee/spec/features/registrations/saas/**/*' + - 'ee/spec/features/trials/saas/**/*' RSpec/DuplicateSpecLocation: Enabled: true diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index 3e8894d2463..506763f5d68 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -1056,6 +1056,7 @@ unencoded unencoder unencodes unencrypted +unescaped unfollow unfollowed unfollows @@ -1075,6 +1076,7 @@ unoptimize unoptimized unoptimizes unoptimizing +unparsable unpatched unpause unprioritized diff --git a/doc/api/group_protected_branches.md b/doc/api/group_protected_branches.md index db648f6870e..db42ca98f0e 100644 --- a/doc/api/group_protected_branches.md +++ b/doc/api/group_protected_branches.md @@ -167,7 +167,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ | `allowed_to_merge` | array | no | Array of access levels allowed to merge, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. | | `allowed_to_push` | array | no | Array of access levels allowed to push, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. | | `allowed_to_unprotect` | array | no | Array of access levels allowed to unprotect, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. | -| `code_owner_approval_required` | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/code_owners.md). Default: `false`. | +| `code_owner_approval_required` | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/codeowners/index.md). Default: `false`. | | `merge_access_level` | integer | no | Access levels allowed to merge. Defaults: `40`, Maintainer role. | | `push_access_level` | integer | no | Access levels allowed to push. Defaults: `40`, Maintainer role. | | `unprotect_access_level` | integer | no | Access levels allowed to unprotect. Defaults: `40`, Maintainer role. | @@ -382,7 +382,7 @@ curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" \ | `allowed_to_push` | array | no | Array of push access levels, with each described by a hash. | | `allowed_to_merge` | array | no | Array of merge access levels, with each described by a hash. | | `allowed_to_unprotect` | array | no | Array of unprotect access levels, with each described by a hash. | -| `code_owner_approval_required` | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/code_owners.md). Default: `false`. | +| `code_owner_approval_required` | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/codeowners/index.md). Default: `false`. | Elements in the `allowed_to_push`, `allowed_to_merge` and `allowed_to_unprotect` arrays should: diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 6c3bd63bbad..9bd220f0406 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -214,7 +214,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla | `allowed_to_merge` **(PREMIUM)** | array | no | Array of access levels allowed to merge, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. | `allowed_to_push` **(PREMIUM)** | array | no | Array of access levels allowed to push, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. | `allowed_to_unprotect` **(PREMIUM)** | array | no | Array of access levels allowed to unprotect, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. The access level `No access` is not available for this field. | -| `code_owner_approval_required` **(PREMIUM)** | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/code_owners.md). (defaults: false) +| `code_owner_approval_required` **(PREMIUM)** | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/codeowners/index.md). (defaults: false) | `merge_access_level` | integer | no | Access levels allowed to merge. (defaults: `40`, Maintainer role) | `push_access_level` | integer | no | Access levels allowed to push. (defaults: `40`, Maintainer role) | `unprotect_access_level` | integer | no | Access levels allowed to unprotect. (defaults: `40`, Maintainer role) @@ -445,7 +445,7 @@ curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitl | `allowed_to_push` **(PREMIUM)** | array | no | Array of push access levels, with each described by a hash. | `allowed_to_merge` **(PREMIUM)** | array | no | Array of merge access levels, with each described by a hash. | `allowed_to_unprotect` **(PREMIUM)** | array | no | Array of unprotect access levels, with each described by a hash. The access level `No access` is not available for this field. -| `code_owner_approval_required` **(PREMIUM)** | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/code_owners.md). Defaults to `false`. | +| `code_owner_approval_required` **(PREMIUM)** | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/codeowners/index.md). Defaults to `false`. | Elements in the `allowed_to_push`, `allowed_to_merge` and `allowed_to_unprotect` arrays should be one of `user_id`, `group_id` or `access_level`, and take the form `{user_id: integer}`, `{group_id: integer}` or diff --git a/doc/development/code_owners/index.md b/doc/development/code_owners/index.md index e4a9cf0c290..d962a36b497 100644 --- a/doc/development/code_owners/index.md +++ b/doc/development/code_owners/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219916) in GitLab 15.10. This document was created to help contributors understand the code design of -[Code Owners](../../user/project/code_owners.md). You should read this +[Code Owners](../../user/project/codeowners/index.md). You should read this document before making changes to the code for this feature. This document is intentionally limited to an overview of how the code is diff --git a/doc/development/features_inside_dot_gitlab.md b/doc/development/features_inside_dot_gitlab.md index dda2c05288f..75290f47f91 100644 --- a/doc/development/features_inside_dot_gitlab.md +++ b/doc/development/features_inside_dot_gitlab.md @@ -13,7 +13,7 @@ When implementing new features, please refer to these existing features to avoid - [Issue Templates](../user/project/description_templates.md#create-an-issue-template): `.gitlab/issue_templates/`. - [Merge request Templates](../user/project/description_templates.md#create-a-merge-request-template): `.gitlab/merge_request_templates/`. - [GitLab agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/configuration_repository.md#layout): `.gitlab/agents/`. -- [CODEOWNERS](../user/project/code_owners.md#set-up-code-owners): `.gitlab/CODEOWNERS`. +- [CODEOWNERS](../user/project/codeowners/index.md#set-up-code-owners): `.gitlab/CODEOWNERS`. - [Route Maps](../ci/review_apps/index.md#route-maps): `.gitlab/route-map.yml`. - [Customize Auto DevOps Helm Values](../topics/autodevops/customize.md#customize-helm-chart-values): `.gitlab/auto-deploy-values.yaml`. - [Insights](../user/project/insights/index.md#configure-project-insights): `.gitlab/insights.yml`. diff --git a/doc/development/merge_request_concepts/index.md b/doc/development/merge_request_concepts/index.md index 8e9b586d5b0..8bec5e0c0b0 100644 --- a/doc/development/merge_request_concepts/index.md +++ b/doc/development/merge_request_concepts/index.md @@ -61,7 +61,7 @@ Additionally, approval settings provide configuration options to define how thos Examples of approval rules and settings include: - [Merge request approval rules](../../user/project/merge_requests/approvals/rules.md) -- [Code owner approvals](../../user/project/code_owners.md) +- [Code owner approvals](../../user/project/codeowners/index.md) - [Security approvals](../../user/application_security/index.md#security-approvals-in-merge-requests) - [Prevent editing approval rules](../../user/project/merge_requests/approvals/settings.md#prevent-editing-approval-rules-in-merge-requests) - [Remove all approvals when commits are added](../../user/project/merge_requests/approvals/settings.md#remove-all-approvals-when-commits-are-added-to-the-source-branch) diff --git a/doc/install/cloud_providers.md b/doc/install/cloud_providers.md new file mode 100644 index 00000000000..36cda77143f --- /dev/null +++ b/doc/install/cloud_providers.md @@ -0,0 +1,17 @@ +--- +stage: Systems +group: Distribution +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: Install GitLab on a cloud provider. +type: index +--- + +# Installing GitLab on a cloud provider **(FREE SELF)** + +You can install GitLab on several cloud providers. + +| Cloud provider | Description | +|---------------------------------------------------------------|-------------| +| [AWS](aws/index.md) | Install GitLab on AWS using the community AMIs provided by GitLab. | +| [Google Cloud Platform (GCP)](google_cloud_platform/index.md) | Install GitLab on a VM in GCP. | +| [Azure](azure/index.md) | Install GitLab from Azure Marketplace. | diff --git a/doc/install/index.md b/doc/install/index.md index 292b00e2775..15556117b51 100644 --- a/doc/install/index.md +++ b/doc/install/index.md @@ -10,10 +10,15 @@ type: index You can install GitLab on most GNU/Linux distributions, on several cloud providers, and in Kubernetes clusters. - To get the best experience, you should balance performance, reliability, ease of administration (backups, upgrades, and troubleshooting) with the cost of hosting. -To get started, [choose your installation method](install_methods.md). - -If you already have a running instance, learn how to [configure it](next_steps.md). +- [Requirements](requirements.md) +- [Installation methods](install_methods.md) +- [Cloud provider guides](cloud_providers.md) +- [Offline GitLab](../topics/offline/index.md) +- [Reference architectures](../administration/reference_architectures/index.md) +- [Steps after installing](next_steps.md) +- [Upgrade GitLab](../update/index.md) +- [Install GitLab Runner](https://docs.gitlab.com/runner/install/) +- [Configure GitLab Runner](https://docs.gitlab.com/runner/configuration/) diff --git a/doc/install/install_methods.md b/doc/install/install_methods.md index 9331e81efa9..0463c926286 100644 --- a/doc/install/install_methods.md +++ b/doc/install/install_methods.md @@ -6,9 +6,10 @@ description: Read through the GitLab installation methods. type: index --- -# Installation methods +# Installation methods **(FREE SELF)** -You can install GitLab by using any of the following methods. +You can install GitLab on several [cloud providers](cloud_providers.md), +or use one of the following methods. | Installation method | Description | When to choose | |----------------------------------------------------------------|-------------|----------------| @@ -19,16 +20,6 @@ You can install GitLab by using any of the following methods. | [GitLab Environment Toolkit (GET)](https://gitlab.com/gitlab-org/gitlab-environment-toolkit#documentation) | A set of automation tools. | Use to deploy a [reference architecture](../administration/reference_architectures/index.md) on most major cloud providers. Has some [limitations](https://gitlab.com/gitlab-org/gitlab-environment-toolkit#missing-features-to-be-aware-of) and manual setup for production environments. | | [GitLab Operator](https://docs.gitlab.com/operator/) | An installation and management method that follows the [Kubernetes Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/). | Use to run GitLab in an [OpenShift](openshift_and_gitlab/index.md) environment. | -## Cloud providers - -You can install GitLab on several cloud providers. - -| Cloud provider | Description | -|---------------------------------------------------------------|-------------| -| [AWS](aws/index.md) | Install GitLab on AWS using the community AMIs provided by GitLab. | -| [Google Cloud Platform (GCP)](google_cloud_platform/index.md) | Install GitLab on a VM in GCP. | -| [Azure](azure/index.md) | Install GitLab from Azure Marketplace. | - ## Unsupported Linux distributions and Unix-like operating systems - Arch Linux diff --git a/doc/subscriptions/bronze_starter.md b/doc/subscriptions/bronze_starter.md index 632177754f4..b076987c0ae 100644 --- a/doc/subscriptions/bronze_starter.md +++ b/doc/subscriptions/bronze_starter.md @@ -18,7 +18,7 @@ the tiers are no longer mentioned in GitLab documentation: - [Activate GitLab EE with a license](../user/admin_area/license.md) - [Add a help message to the sign-in page](../user/admin_area/settings/help_page.md#add-a-help-message-to-the-sign-in-page) - [Burndown and burnup charts](../user/project/milestones/burndown_and_burnup_charts.md) in the [Milestone View](../user/project/milestones/index.md#burndown-charts), -- [Code owners](../user/project/code_owners.md) +- [Code owners](../user/project/codeowners/index.md) - Description templates: - [Setting a default template for merge requests and issues](../user/project/description_templates.md#set-a-default-template-for-merge-requests-and-issues) - [Email from GitLab](../user/admin_area/email_from_gitlab.md) diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 13837d480f3..a76432e9af6 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -140,7 +140,7 @@ To see the full list of customizations available, see the Helm chart's [default ##### Use the agent when KAS is behind a self-signed certificate -When [KAS]((../../../../administration/clusters/kas.md) is behind a self-signed certificate, +When [KAS](../../../../administration/clusters/kas.md) is behind a self-signed certificate, you can set the value of `config.caCert` to the certificate. For example: ```shell diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 6e2206d27be..f9244177aa5 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -1,647 +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. - -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](#code-owners-syntax-reference). - 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`. - -### Groups as Code Owners - -> 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 -``` - -### 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**. - -## 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 -``` - -## Code Owners syntax reference - -### Comments - -Lines beginning with `#` are ignored: - -```codeowners -# This is a comment -``` - -### Sections - -Sections are groups of entries. A section begins with a section heading in square brackets, followed by the entries. - -```codeowners -[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. - -```codeowners -# 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 are combined](#sections-with-duplicate-names). - -```codeowners -[Section name] -``` - -### Required sections - -Required sections do not include `^` before the [section name](#section-names). - -```codeowners -[Required section] -``` - -### Optional sections - -Optional sections include a `^` before the [section name](#section-names). - -```codeowners -^[Optional section] -``` - -### Sections requiring multiple approvals - -Sections requiring multiple approvals include the number of approvals in square brackets after the [section name](#section-names). - -```codeowners -[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). - -```codeowners -# 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. - -```codeowners -README.md @username1 -``` - -NOTE: -If an entry is duplicated in a section, [the last entry is used from each section.](#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` - -```codeowners -# 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. - -```codeowners -# 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. - -```codeowners -# This is the same as `/docs/**/*` -/docs/ -``` - -### Wildcard paths - -Wildcards can be used to match one of more characters of a path. - -```codeowners -# 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. - -```codeowners -# 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. - -```codeowners -/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 [Groups as Code Owners section](#groups-as-code-owners). - -```codeowners -/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). - -```codeowners -/path/to/entry.rb @username1 -/path/to/entry.rb @username1 @username2 -``` - -## Technical Resources - -[Code Owners development guidelines](../../../ee/development/code_owners/index.md) - -## 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. -- 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. +<!-- 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..cbf6cc2c186 --- /dev/null +++ b/doc/user/project/codeowners/index.md @@ -0,0 +1,732 @@ +--- +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](#code-owners-syntax-reference). + 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`. + +### Groups as Code Owners + +> 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 +``` + +### 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**. + +## 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 [Groups as Code Owners](#groups-as-code-owners). + +### 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](#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 +``` + +## Code Owners syntax reference + +### Comments + +Lines beginning with `#` are ignored: + +```codeowners +# This is a comment +``` + +### Sections + +Sections are groups of entries. A section begins with a section heading in square brackets, followed by the entries. + +```codeowners +[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. + +```codeowners +# 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 are combined](#sections-with-duplicate-names). + +```codeowners +[Section name] +``` + +### Required sections + +Required sections do not include `^` before the [section name](#section-names). + +```codeowners +[Required section] +``` + +### Optional sections + +Optional sections include a `^` before the [section name](#section-names). + +```codeowners +^[Optional section] +``` + +### Sections requiring multiple approvals + +Sections requiring multiple approvals include the number of approvals in square brackets after the [section name](#section-names). + +```codeowners +[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). + +```codeowners +# 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. + +```codeowners +README.md @username1 +``` + +NOTE: +If an entry is duplicated in a section, [the last entry is used from each section.](#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` + +```codeowners +# 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. + +```codeowners +# 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. + +```codeowners +# This is the same as `/docs/**/*` +/docs/ +``` + +### Wildcard paths + +Wildcards can be used to match one of more characters of a path. + +```codeowners +# 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. + +```codeowners +# 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. + +```codeowners +/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 [Groups as Code Owners section](#groups-as-code-owners). + +```codeowners +/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). + +```codeowners +/path/to/entry.rb @username1 +/path/to/entry.rb @username1 @username2 +``` + +## Technical Resources + +[Code Owners development guidelines](../../../development/code_owners/index.md) + +## 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. +- 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/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index e9d6593986b..3d455178938 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -16,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 @@ -35,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. diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 7ffb05cb4f1..786897c18c9 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -161,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**. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 2a11236f9f0..c13aaa132c9 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). diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index f760b1b730a..0a526e1d268 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -84,7 +84,7 @@ To filter the list of merge requests: - 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: diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 4944d59ec37..0b2f6587f6f 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -172,7 +172,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: diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 496db740733..d4115548fca 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -270,7 +270,7 @@ Members who can push to this branch can now also force push. > [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: diff --git a/spec/frontend/analytics/shared/components/projects_dropdown_filter_spec.js b/spec/frontend/analytics/shared/components/projects_dropdown_filter_spec.js index d2cbe0d39e4..ade8a61fdce 100644 --- a/spec/frontend/analytics/shared/components/projects_dropdown_filter_spec.js +++ b/spec/frontend/analytics/shared/components/projects_dropdown_filter_spec.js @@ -1,4 +1,4 @@ -import { GlDropdown, GlDropdownItem, GlTruncate } from '@gitlab/ui'; +import { GlDropdown, GlDropdownItem, GlTruncate, GlSearchBoxByType } from '@gitlab/ui'; import { nextTick } from 'vue'; import { mountExtended } from 'helpers/vue_test_utils_helper'; import { stubComponent } from 'helpers/stub_component'; @@ -31,6 +31,7 @@ const projects = [ const MockGlDropdown = stubComponent(GlDropdown, { template: ` <div> + <slot name="header"></slot> <div data-testid="vsa-highlighted-items"> <slot name="highlighted-items"></slot> </div> @@ -112,6 +113,8 @@ describe('ProjectsDropdownFilter component', () => { const selectedIds = () => wrapper.vm.selectedProjects.map(({ id }) => id); + const findSearchBoxByType = () => wrapper.findComponent(GlSearchBoxByType); + describe('queryParams are applied when fetching data', () => { beforeEach(() => { createComponent({ @@ -123,9 +126,7 @@ describe('ProjectsDropdownFilter component', () => { }); it('applies the correct queryParams when making an api call', async () => { - // setData usage is discouraged. See https://gitlab.com/groups/gitlab-org/-/epics/7330 for details - // eslint-disable-next-line no-restricted-syntax - wrapper.setData({ searchTerm: 'gitlab' }); + findSearchBoxByType().vm.$emit('input', 'gitlab'); expect(spyQuery).toHaveBeenCalledTimes(1); @@ -144,6 +145,7 @@ describe('ProjectsDropdownFilter component', () => { describe('highlighted items', () => { const blockDefaultProps = { multiSelect: true }; + beforeEach(() => { createComponent(blockDefaultProps); }); @@ -151,6 +153,7 @@ describe('ProjectsDropdownFilter component', () => { describe('with no project selected', () => { it('does not render the highlighted items', async () => { await createWithMockDropdown(blockDefaultProps); + expect(findSelectedDropdownItems().length).toBe(0); }); @@ -188,8 +191,7 @@ describe('ProjectsDropdownFilter component', () => { expect(findSelectedProjectsLabel().text()).toBe('2 projects selected'); - findClearAllButton().trigger('click'); - await nextTick(); + await findClearAllButton().trigger('click'); expect(findSelectedProjectsLabel().text()).toBe('Select projects'); }); @@ -201,9 +203,7 @@ describe('ProjectsDropdownFilter component', () => { await createWithMockDropdown({ multiSelect: true }); selectDropdownItemAtIndex(0); - // setData usage is discouraged. See https://gitlab.com/groups/gitlab-org/-/epics/7330 for details - // eslint-disable-next-line no-restricted-syntax - wrapper.setData({ searchTerm: 'this is a very long search string' }); + findSearchBoxByType().vm.$emit('input', 'this is a very long search string'); }); it('renders the highlighted items', async () => { @@ -351,17 +351,19 @@ describe('ProjectsDropdownFilter component', () => { it('should remove from selection when clicked again', () => { selectDropdownItemAtIndex(0); + expect(selectedIds()).toEqual([projects[0].id]); selectDropdownItemAtIndex(0); + expect(selectedIds()).toEqual([]); }); it('renders the correct placeholder text when multiple projects are selected', async () => { selectDropdownItemAtIndex(0); selectDropdownItemAtIndex(1); - await nextTick(); + expect(findDropdownButton().text()).toBe('2 projects selected'); }); }); diff --git a/spec/frontend/ci/ci_variable_list/components/ci_admin_variables_spec.js b/spec/frontend/ci/ci_variable_list/components/ci_admin_variables_spec.js index 8e012883f09..1d0dcf242a4 100644 --- a/spec/frontend/ci/ci_variable_list/components/ci_admin_variables_spec.js +++ b/spec/frontend/ci/ci_variable_list/components/ci_admin_variables_spec.js @@ -1,7 +1,16 @@ import { shallowMount } from '@vue/test-utils'; +import { + ADD_MUTATION_ACTION, + DELETE_MUTATION_ACTION, + UPDATE_MUTATION_ACTION, +} from '~/ci/ci_variable_list/constants'; import ciAdminVariables from '~/ci/ci_variable_list/components/ci_admin_variables.vue'; import ciVariableShared from '~/ci/ci_variable_list/components/ci_variable_shared.vue'; +import addAdminVariable from '~/ci/ci_variable_list/graphql/mutations/admin_add_variable.mutation.graphql'; +import deleteAdminVariable from '~/ci/ci_variable_list/graphql/mutations/admin_delete_variable.mutation.graphql'; +import updateAdminVariable from '~/ci/ci_variable_list/graphql/mutations/admin_update_variable.mutation.graphql'; +import getAdminVariables from '~/ci/ci_variable_list/graphql/queries/variables.query.graphql'; describe('Ci Project Variable wrapper', () => { let wrapper; @@ -22,8 +31,17 @@ describe('Ci Project Variable wrapper', () => { componentName: 'InstanceVariables', entity: '', hideEnvironmentScope: true, - mutationData: wrapper.vm.$options.mutationData, - queryData: wrapper.vm.$options.queryData, + mutationData: { + [ADD_MUTATION_ACTION]: addAdminVariable, + [UPDATE_MUTATION_ACTION]: updateAdminVariable, + [DELETE_MUTATION_ACTION]: deleteAdminVariable, + }, + queryData: { + ciVariables: { + lookup: expect.any(Function), + query: getAdminVariables, + }, + }, refetchAfterMutation: true, fullPath: null, id: null, diff --git a/spec/frontend/ci/ci_variable_list/components/ci_group_variables_spec.js b/spec/frontend/ci/ci_variable_list/components/ci_group_variables_spec.js index 77d90a7667d..7436210fe70 100644 --- a/spec/frontend/ci/ci_variable_list/components/ci_group_variables_spec.js +++ b/spec/frontend/ci/ci_variable_list/components/ci_group_variables_spec.js @@ -4,6 +4,15 @@ import { convertToGraphQLId } from '~/graphql_shared/utils'; import ciGroupVariables from '~/ci/ci_variable_list/components/ci_group_variables.vue'; import ciVariableShared from '~/ci/ci_variable_list/components/ci_variable_shared.vue'; +import { + ADD_MUTATION_ACTION, + DELETE_MUTATION_ACTION, + UPDATE_MUTATION_ACTION, +} from '~/ci/ci_variable_list/constants'; +import getGroupVariables from '~/ci/ci_variable_list/graphql/queries/group_variables.query.graphql'; +import addGroupVariable from '~/ci/ci_variable_list/graphql/mutations/group_add_variable.mutation.graphql'; +import deleteGroupVariable from '~/ci/ci_variable_list/graphql/mutations/group_delete_variable.mutation.graphql'; +import updateGroupVariable from '~/ci/ci_variable_list/graphql/mutations/group_update_variable.mutation.graphql'; const mockProvide = { glFeatures: { @@ -37,8 +46,17 @@ describe('Ci Group Variable wrapper', () => { entity: 'group', fullPath: mockProvide.groupPath, hideEnvironmentScope: false, - mutationData: wrapper.vm.$options.mutationData, - queryData: wrapper.vm.$options.queryData, + mutationData: { + [ADD_MUTATION_ACTION]: addGroupVariable, + [UPDATE_MUTATION_ACTION]: updateGroupVariable, + [DELETE_MUTATION_ACTION]: deleteGroupVariable, + }, + queryData: { + ciVariables: { + lookup: expect.any(Function), + query: getGroupVariables, + }, + }, refetchAfterMutation: false, }); }); diff --git a/spec/frontend/ci/ci_variable_list/components/ci_project_variables_spec.js b/spec/frontend/ci/ci_variable_list/components/ci_project_variables_spec.js index ce5237a84f7..69b0d4261b2 100644 --- a/spec/frontend/ci/ci_variable_list/components/ci_project_variables_spec.js +++ b/spec/frontend/ci/ci_variable_list/components/ci_project_variables_spec.js @@ -4,6 +4,16 @@ import { convertToGraphQLId } from '~/graphql_shared/utils'; import ciProjectVariables from '~/ci/ci_variable_list/components/ci_project_variables.vue'; import ciVariableShared from '~/ci/ci_variable_list/components/ci_variable_shared.vue'; +import { + ADD_MUTATION_ACTION, + DELETE_MUTATION_ACTION, + UPDATE_MUTATION_ACTION, +} from '~/ci/ci_variable_list/constants'; +import getProjectEnvironments from '~/ci/ci_variable_list/graphql/queries/project_environments.query.graphql'; +import getProjectVariables from '~/ci/ci_variable_list/graphql/queries/project_variables.query.graphql'; +import addProjectVariable from '~/ci/ci_variable_list/graphql/mutations/project_add_variable.mutation.graphql'; +import deleteProjectVariable from '~/ci/ci_variable_list/graphql/mutations/project_delete_variable.mutation.graphql'; +import updateProjectVariable from '~/ci/ci_variable_list/graphql/mutations/project_update_variable.mutation.graphql'; const mockProvide = { projectFullPath: '/namespace/project', @@ -33,8 +43,21 @@ describe('Ci Project Variable wrapper', () => { entity: 'project', fullPath: mockProvide.projectFullPath, hideEnvironmentScope: false, - mutationData: wrapper.vm.$options.mutationData, - queryData: wrapper.vm.$options.queryData, + mutationData: { + [ADD_MUTATION_ACTION]: addProjectVariable, + [UPDATE_MUTATION_ACTION]: updateProjectVariable, + [DELETE_MUTATION_ACTION]: deleteProjectVariable, + }, + queryData: { + ciVariables: { + lookup: expect.any(Function), + query: getProjectVariables, + }, + environments: { + lookup: expect.any(Function), + query: getProjectEnvironments, + }, + }, refetchAfterMutation: false, }); }); diff --git a/spec/frontend/ci/ci_variable_list/components/ci_variable_shared_spec.js b/spec/frontend/ci/ci_variable_list/components/ci_variable_shared_spec.js index 66b41223b33..4107b08e9a4 100644 --- a/spec/frontend/ci/ci_variable_list/components/ci_variable_shared_spec.js +++ b/spec/frontend/ci/ci_variable_list/components/ci_variable_shared_spec.js @@ -1,4 +1,4 @@ -import Vue, { nextTick } from 'vue'; +import Vue from 'vue'; import VueApollo from 'vue-apollo'; import { GlLoadingIcon, GlTable } from '@gitlab/ui'; import { shallowMount } from '@vue/test-utils'; @@ -6,8 +6,6 @@ import createMockApollo from 'helpers/mock_apollo_helper'; import waitForPromises from 'helpers/wait_for_promises'; import { createAlert } from '~/alert'; import { resolvers } from '~/ci/ci_variable_list/graphql/settings'; -import { TYPENAME_GROUP } from '~/graphql_shared/constants'; -import { convertToGraphQLId } from '~/graphql_shared/utils'; import ciVariableShared from '~/ci/ci_variable_list/components/ci_variable_shared.vue'; import ciVariableSettings from '~/ci/ci_variable_list/components/ci_variable_settings.vue'; @@ -18,10 +16,7 @@ import getGroupVariables from '~/ci/ci_variable_list/graphql/queries/group_varia import getProjectVariables from '~/ci/ci_variable_list/graphql/queries/project_variables.query.graphql'; import { - ADD_MUTATION_ACTION, - DELETE_MUTATION_ACTION, ENVIRONMENT_QUERY_LIMIT, - UPDATE_MUTATION_ACTION, environmentFetchErrorText, genericMutationErrorText, variableFetchErrorText, @@ -65,6 +60,10 @@ describe('Ci Variable Shared Component', () => { let mockApollo; let mockEnvironments; + let mockMutation; + let mockAddMutation; + let mockUpdateMutation; + let mockDeleteMutation; let mockVariables; const mockToastShow = jest.fn(); @@ -76,6 +75,7 @@ describe('Ci Variable Shared Component', () => { // eslint-disable-next-line consistent-return function createComponentWithApollo({ customHandlers = null, + customResolvers = null, isLoading = false, props = { ...createProjectProps() }, provide = {}, @@ -85,7 +85,9 @@ describe('Ci Variable Shared Component', () => { [getProjectVariables, mockVariables], ]; - mockApollo = createMockApollo(handlers, resolvers); + const mutationResolvers = customResolvers || resolvers; + + mockApollo = createMockApollo(handlers, mutationResolvers); wrapper = shallowMount(ciVariableShared, { propsData: { @@ -113,6 +115,10 @@ describe('Ci Variable Shared Component', () => { beforeEach(() => { mockEnvironments = jest.fn(); mockVariables = jest.fn(); + mockMutation = jest.fn(); + mockAddMutation = jest.fn(); + mockUpdateMutation = jest.fn(); + mockDeleteMutation = jest.fn(); }); describe.each` @@ -197,9 +203,7 @@ describe('Ci Variable Shared Component', () => { describe('environment query', () => { describe('when there is an environment key in queryData', () => { beforeEach(() => { - mockEnvironments - .mockResolvedValueOnce(mockProjectEnvironments) - .mockResolvedValueOnce(mockProjectEnvironments); + mockEnvironments.mockResolvedValue(mockProjectEnvironments); mockVariables.mockResolvedValue(mockProjectVariables); }); @@ -287,107 +291,194 @@ describe('Ci Variable Shared Component', () => { describe('mutations', () => { const groupProps = createGroupProps(); + const instanceProps = createInstanceProps(); + const projectProps = createProjectProps(); - beforeEach(async () => { - mockVariables.mockResolvedValue(mockGroupVariables); - - await createComponentWithApollo({ - customHandlers: [[getGroupVariables, mockVariables]], - props: groupProps, - provide: pagesFeatureFlagProvide, - }); - }); - it.each` - actionName | mutation | event - ${'add'} | ${groupProps.mutationData[ADD_MUTATION_ACTION]} | ${'add-variable'} - ${'update'} | ${groupProps.mutationData[UPDATE_MUTATION_ACTION]} | ${'update-variable'} - ${'delete'} | ${groupProps.mutationData[DELETE_MUTATION_ACTION]} | ${'delete-variable'} - `( - 'calls the mutation from propsData and shows a toast when user performs $actionName variable', - async ({ event, mutation, actionName }) => { - jest.spyOn(wrapper.vm.$apollo, 'mutate').mockResolvedValue({ data: {} }); + let mockMutationMap; - await findCiSettings().vm.$emit(event, newVariable); + describe('error handling and feedback', () => { + beforeEach(async () => { + mockVariables.mockResolvedValue(mockGroupVariables); + mockMutation.mockResolvedValue({ ...mockGroupVariables.data, errors: [] }); - expect(wrapper.vm.$apollo.mutate).toHaveBeenCalledWith({ - mutation, - variables: { - endpoint: mockProvide.endpoint, - fullPath: groupProps.fullPath, - id: convertToGraphQLId(TYPENAME_GROUP, groupProps.id), - variable: newVariable, + await createComponentWithApollo({ + customHandlers: [[getGroupVariables, mockVariables]], + customResolvers: { + Mutation: { + ...resolvers.Mutation, + addGroupVariable: mockMutation, + updateGroupVariable: mockMutation, + deleteGroupVariable: mockMutation, + }, }, + props: groupProps, + provide: pagesFeatureFlagProvide, }); + }); + + it.each` + actionName | event + ${'add'} | ${'add-variable'} + ${'update'} | ${'update-variable'} + ${'delete'} | ${'delete-variable'} + `( + 'throws the specific graphql error if present when user performs $actionName variable', + async ({ event }) => { + const graphQLErrorMessage = 'There is a problem with this graphQL action'; + mockMutation.mockResolvedValue({ + ...mockGroupVariables.data, + errors: [graphQLErrorMessage], + }); - await nextTick(); + await findCiSettings().vm.$emit(event, newVariable); + await waitForPromises(); - expect(mockToastShow).toHaveBeenCalledWith( - mapMutationActionToToast[actionName](newVariable.key), - ); - }, - ); + expect(mockMutation).toHaveBeenCalled(); + expect(createAlert).toHaveBeenCalledWith({ message: graphQLErrorMessage }); + }, + ); - it.each` - actionName | event - ${'add'} | ${'add-variable'} - ${'update'} | ${'update-variable'} - ${'delete'} | ${'delete-variable'} - `( - 'throws with the specific graphql error if present when user performs $actionName variable', - async ({ event }) => { - const graphQLErrorMessage = 'There is a problem with this graphQL action'; - jest - .spyOn(wrapper.vm.$apollo, 'mutate') - .mockResolvedValue({ data: { ciVariableMutation: { errors: [graphQLErrorMessage] } } }); - await findCiSettings().vm.$emit(event, newVariable); - await nextTick(); - - expect(wrapper.vm.$apollo.mutate).toHaveBeenCalled(); - expect(createAlert).toHaveBeenCalledWith({ message: graphQLErrorMessage }); - }, - ); + it.each` + actionName | event + ${'add'} | ${'add-variable'} + ${'update'} | ${'update-variable'} + ${'delete'} | ${'delete-variable'} + `( + 'throws generic error on failure with no graphql errors and user performs $actionName variable', + async ({ event }) => { + mockMutation.mockRejectedValue(); + + await findCiSettings().vm.$emit(event, newVariable); + await waitForPromises(); - it.each` - actionName | event - ${'add'} | ${'add-variable'} - ${'update'} | ${'update-variable'} - ${'delete'} | ${'delete-variable'} + expect(mockMutation).toHaveBeenCalled(); + expect(createAlert).toHaveBeenCalledWith({ message: genericMutationErrorText }); + }, + ); + + it.each` + actionName | event + ${'add'} | ${'add-variable'} + ${'update'} | ${'update-variable'} + ${'delete'} | ${'delete-variable'} + `( + 'displays toast message after user performs $actionName variable', + async ({ actionName, event }) => { + await findCiSettings().vm.$emit(event, newVariable); + await waitForPromises(); + + expect(mockMutation).toHaveBeenCalled(); + expect(mockToastShow).toHaveBeenCalledWith( + mapMutationActionToToast[actionName](newVariable.key), + ); + }, + ); + }); + + const setupMockMutations = (mockResolvedMutation) => { + mockAddMutation.mockResolvedValue(mockResolvedMutation); + mockUpdateMutation.mockResolvedValue(mockResolvedMutation); + mockDeleteMutation.mockResolvedValue(mockResolvedMutation); + + return { + add: mockAddMutation, + update: mockUpdateMutation, + delete: mockDeleteMutation, + }; + }; + + describe.each` + scope | mockVariablesResolvedValue | getVariablesHandler | addMutationName | updateMutationName | deleteMutationName | props + ${'instance'} | ${mockVariables} | ${getAdminVariables} | ${'addAdminVariable'} | ${'updateAdminVariable'} | ${'deleteAdminVariable'} | ${instanceProps} + ${'group'} | ${mockGroupVariables} | ${getGroupVariables} | ${'addGroupVariable'} | ${'updateGroupVariable'} | ${'deleteGroupVariable'} | ${groupProps} + ${'project'} | ${mockProjectVariables} | ${getProjectVariables} | ${'addProjectVariable'} | ${'updateProjectVariable'} | ${'deleteProjectVariable'} | ${projectProps} `( - 'throws generic error on failure with no graphql errors and user performs $actionName variable', - async ({ event }) => { - jest.spyOn(wrapper.vm.$apollo, 'mutate').mockImplementationOnce(() => { - throw new Error(); + '$scope variable mutations', + ({ + addMutationName, + deleteMutationName, + getVariablesHandler, + mockVariablesResolvedValue, + updateMutationName, + props, + }) => { + beforeEach(async () => { + mockVariables.mockResolvedValue(mockVariablesResolvedValue); + mockMutationMap = setupMockMutations({ ...mockVariables.data, errors: [] }); + + await createComponentWithApollo({ + customHandlers: [[getVariablesHandler, mockVariables]], + customResolvers: { + Mutation: { + ...resolvers.Mutation, + [addMutationName]: mockAddMutation, + [updateMutationName]: mockUpdateMutation, + [deleteMutationName]: mockDeleteMutation, + }, + }, + props, + provide: pagesFeatureFlagProvide, + }); }); - await findCiSettings().vm.$emit(event, newVariable); - expect(wrapper.vm.$apollo.mutate).toHaveBeenCalled(); - expect(createAlert).toHaveBeenCalledWith({ message: genericMutationErrorText }); + it.each` + actionName | event + ${'add'} | ${'add-variable'} + ${'update'} | ${'update-variable'} + ${'delete'} | ${'delete-variable'} + `( + 'calls the right mutation when user performs $actionName variable', + async ({ event, actionName }) => { + await findCiSettings().vm.$emit(event, newVariable); + await waitForPromises(); + + expect(mockMutationMap[actionName]).toHaveBeenCalledWith( + expect.anything(), + { + endpoint: mockProvide.endpoint, + fullPath: props.fullPath, + id: props.id, + variable: newVariable, + }, + expect.anything(), + expect.anything(), + ); + }, + ); }, ); describe('without fullpath and ID props', () => { beforeEach(async () => { + mockMutation.mockResolvedValue({ ...mockAdminVariables.data, errors: [] }); mockVariables.mockResolvedValue(mockAdminVariables); await createComponentWithApollo({ customHandlers: [[getAdminVariables, mockVariables]], + customResolvers: { + Mutation: { + ...resolvers.Mutation, + addAdminVariable: mockMutation, + }, + }, props: createInstanceProps(), provide: pagesFeatureFlagProvide, }); }); it('does not pass fullPath and ID to the mutation', async () => { - jest.spyOn(wrapper.vm.$apollo, 'mutate').mockResolvedValue(); - await findCiSettings().vm.$emit('add-variable', newVariable); + await waitForPromises(); - expect(wrapper.vm.$apollo.mutate).toHaveBeenCalledWith({ - mutation: wrapper.props().mutationData[ADD_MUTATION_ACTION], - variables: { + expect(mockMutation).toHaveBeenCalledWith( + expect.anything(), + { endpoint: mockProvide.endpoint, variable: newVariable, }, - }); + expect.anything(), + expect.anything(), + ); }); }); }); @@ -453,29 +544,29 @@ describe('Ci Variable Shared Component', () => { describe('refetchAfterMutation', () => { it.each` - bool | text - ${true} | ${'refetches the variables'} - ${false} | ${'does not refetch the variables'} - `('when $bool it $text', async ({ bool }) => { + bool | text | timesQueryCalled + ${true} | ${'refetches the variables'} | ${2} + ${false} | ${'does not refetch the variables'} | ${1} + `('when $bool it $text', async ({ bool, timesQueryCalled }) => { + mockMutation.mockResolvedValue({ ...mockAdminVariables.data, errors: [] }); + mockVariables.mockResolvedValue(mockAdminVariables); + await createComponentWithApollo({ + customHandlers: [[getAdminVariables, mockVariables]], + customResolvers: { + Mutation: { + ...resolvers.Mutation, + addAdminVariable: mockMutation, + }, + }, props: { ...createInstanceProps(), refetchAfterMutation: bool }, provide: pagesFeatureFlagProvide, }); - jest.spyOn(wrapper.vm.$apollo, 'mutate').mockResolvedValue({ data: {} }); - jest - .spyOn(wrapper.vm.$apollo.queries.ciVariables, 'refetch') - .mockImplementation(jest.fn()); - await findCiSettings().vm.$emit('add-variable', newVariable); + await waitForPromises(); - await nextTick(); - - if (bool) { - expect(wrapper.vm.$apollo.queries.ciVariables.refetch).toHaveBeenCalled(); - } else { - expect(wrapper.vm.$apollo.queries.ciVariables.refetch).not.toHaveBeenCalled(); - } + expect(mockVariables).toHaveBeenCalledTimes(timesQueryCalled); }); }); |