Migration from CODEOWNERS | Elevatic Documentation

🔰 fundamental topics for beginners getting started with DevSensei
🔬 advanced topics for once you have your first workflows automated

Migration: From `CODEOWNERS` config to DevSensei 🔰

What advantages does `devsensei.yaml` bring compared to `CODEOWNERS`?

devsensei.yaml can share common rules across repositories with included devsensei.yaml files (called "Includes") to reduce duplication and maintenance efforts.
Common configuration parts (e.g. reusing the list of reviewers) can be shared with YAML anchors.
DevSensei allows to precisely declare the automation you need by combining conditions and actions.
DevSensei currently supports the same functionality and more via its actions and merge-checks. See add-reviewers, decline, codeowners-check, and schedule-auto-merge. We will add more actions in the future to automate your pull request workflow. Let us know what actions you are looking for.
devsensei.yaml is read from the default branch of your repository. This will reduce the maintenance efforts significantly when the automation for the repository needs changes.

How can I migrate from `CODEOWNERS` to `devsensei.yaml`?

The migration from CODEOWNERS to devsensei.yaml has been automated, so only minimal effort is required on your part.

Migration prerequisites: The DevSensei app must be installed, and the repository must contain a CODEOWNERS file in the main branch for DevSensei to migrate.

Migrate all or many repositories in the Bitbucket project settings (bulk action)

Install the DevSensei app.
Open the project settings as an admin.
Navigate to the DevSensei migration section.
If a CODEOWNERS file exists in any of the repositories, a migration action is available.
Click Start migration...

Choose either some repositories (Migrate Selected) or all (Migrate all N repositories) depending on your needs. If a repository does not show up in the list, it could be that it has not been indexed yet. Wait a few minutes and try again.

DevSensei generates devsensei.yaml files that mirror the existing CODEOWNERS behavior.
DevSensei creates pull requests containing the generated YAML configuration. You can see statistics how many pull requests have been created, if an error occurred and how many repositories are fully migrated:

Review all the generated pull requests and merge them when you are satisfied with the result.

After all pull requests have been merged, the migration is done and the migration section will no longer be visible.
The Project settings are set on DevSensei mode after the migration.

Migrate a single repository in the Bitbucket repository settings since 9.5

Install the DevSensei app.
Open the repository settings as an admin.
Navigate to the DevSensei migration section.
If a CODEOWNERS file exists in the repository, a migration action is available.
Click Create Migration Pull Request.

DevSensei generates a devsensei.yaml file that mirrors the existing CODEOWNERS behavior.
DevSensei creates a pull request containing the generated YAML configuration.
Review the pull request and merge it when you are satisfied with the result.
The Repository settings are set on DevSensei mode after the migration.

Best practice: Review the generated pull request before merging, especially if your Code Owners setup uses many path patterns or group owners. The migration is automatic, but the PR review gives your team a safe checkpoint.

DevSensei reads the devsensei.yaml configuration from the default branch of your repository for every pull request. This is in contrast to Code Owners configuration in CODEOWNERS file, that is taken from the destination branch of the pull request.

Below you can see both a CODEOWNERS file and the equivalent devsensei.yaml file. This should help you to migrate from your Code Owners rules to the new YAML format (see the matching numbers for the equivalents).

The format of the Code Owners rules is the same, so you can copy that to the rules section of the codeowners custom attribute.

CODEOWNERS

CODEOWNERS.destination_branch_pattern main             # (1)
CODEOWNERS.destination_branch_pattern release/*        # (2)
CODEOWNERS.toplevel.subdirectory_overrides enable      # (3) NOT SUPPORTED, see details in next section
CODEOWNERS.toplevel.assignment_routing random 2        # (4)
CODEOWNERS.toplevel.assignment_limit 20                # (5)
CODEOWNERS.toplevel.create_pull_request_comment enable # (6)
CODEOWNERS.toplevel.auto_unapprove_on_change enable    # (7)
CODEOWNERS.source_branch_exclusion_pattern hotfix/*    # (8)

@@@MyDevs                @PeterTheHacker  @PeterTheJavaExpert ann@scala.lang @@JSDevs

*                        @PeterTheHacker
*.java                   @PeterTheJavaExpert
*.js                     @PaulTheJSGuru @@JSExperts
"a/path with spaces/*"   docs@example.com
!ci/playgrounds.yml
src/components/**/*.js   @@MyDevs

Check(@@MyDevs >= 2)

devsensei.yaml

YAML

shared:
  - custom-groups:
      MyDevs: &MyDevs
        - @PeterTheHacker
        - @PeterTheJavaExpert
        - ann@scala.lang
        - @@JSDevs

workflows:
  - name: Add Code Owners
    conditions:
      - or:
        - destination = 'main'        # (1)
        - destination ~= 'release/*'  # (2)
      - source ~!= 'hotfix/*'         # (8)
    retrigger-on:
      - diff-change # If you want update Code Owners when the pull request code is updated
    custom-attributes:
      custom-groups:
        MyDevs: *MyDevs
      codeowners:
        rules: |
          *                       @PeterTheHacker
          *.java                  @PeterTheJavaExpert
          *.js                    @PaulTheJSGuru @@JSExperts
          "a/path with spaces/*"  docs@example.com
          !ci/playgrounds.yml
          src/components/**/*.js  @@MyDevs
    actions:
      - unapprove:                    # (7)
          members: codeowners
      - add-reviewers:
          members: codeowners
          assignment-routing:
            random: 2                 # (4)
          assignment-limit: 20        # (5)
      - add-comment:                  # (6)
          report-from: add-reviewers
    merge-checks:
      - codeowners-check: |
          Check(@@MyDevs >= 2)

Code Owners Settings NOT supported by DevSensei equivalents 🔬

Code Owners feature	Why not supported / Alternative?
`CODEOWNERS.toplevel.subdirectory_override`	Manually include rule files of sub directories

To replicate the previous behavior of the sub-dir override feature with DevSensei workflows, you must:

prefix the file patterns with the subdir in the corresponding codeowners custom attribute
exclude the subdirs in the "root" codeowners custom attribute with a negation rule

Example: if you have CODEOWNERS with subdirectory_override=true and module-a/CODEOWNERS.

prefix file patterns in migrated codeowners custom attributes of module-a like module-a/PATTERN
add !module-a/ as last rule to migrated root CODEOWNERS action to ignore the sub directory of module-a in this action

Migration: From CODEOWNERS config to DevSensei 🔰

What advantages does devsensei.yaml bring compared to CODEOWNERS?

How can I migrate from CODEOWNERS to devsensei.yaml?