DevSensei | Code Owners for Bitbucket
DevSensei | Code Owners for Bitbucket
Breadcrumbs

Migration from CODEOWNERS

  • 🔰 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?

  1. Enable devsensei.yaml configuration file for your repository:

    1. Navigate to the repository → Repository Setting (⚙️ on the left)

      1. If under add-ons you see DevSensei settings link, then the repository is ready to work with devsensei.yaml config files; move on to step (2.).

      2. else, if you see the Code Owners settings link, click it.

    2. In the settings panel of Code Owners, scroll down until you see the DevSensei panel, which will display a link “Switch to DevSensei”. Click the link.

    3. A modal will pop-up, to remind you that after confirmation only devsensei.yaml files will be taken into account.

    4. in this modal, there should be a button to convert your existing CODEOWNERS file (on the default branch) “Download generated devsensei.yaml”, you can choose to click it here, but it is also available in step (2.)

    5. when ready to switch over the mode, in the modal click the button “Go to DevSensei”.

    6. A similar flow exists in the project and global admin settings.

  2. Convert your existing CODEOWNERS file once in DevSensei mode, you have two options:

    1. Automated migration: migrate your CODEOWNERS file to devsensei.yaml with the built-in migration support

      1. Navigate to the repository → Repository Setting (⚙️ on the left)

        1. in the add-ons submenu in sidebar, click the DevSensei settings link (ensure step (1.) is done first!)

      2. In the settings panel of Code Owners, scroll down until you see the DevSensei panel, which will display a link “Switch to DevSensei”

      3. A modal will pop-up, to remind you that after confirmation only CODEOWNERS files will be taken into account. click the button “Go to legacy Code Owners”.

      4. A similar flow exists in the project and global admin settings.

    2. Manual migration: migrate your CODEOWNERS settings to their equivalents in devsensei.yaml.

      1. Copy the assignment rules from the CODEOWNERS file to the rules section of codeowners custom attribute in devsensei.yaml.

      2. For the settings, use a combination of workflow conditions, and options for the add-reviewers, add-comment, and unapprove actions (see the Actions paragraph below).

      3. For the custom Code Owner groups (e.g. @@@my-group @peter @anna), add a custom-groups custom attribute to the workflow.

      4. For the merge checks, add a codeowners-check to the merge-checks section of a workflow.

  3. push the devsensei.yaml file to the root directory in the default branch of your repository

  4. enable DevSensei under repository settings -> DevSensei | Code Owners -> DevSensei Workflows -> Enabled

  5. when the app sees a devsensei.yaml file, it will use that instead of CODEOWNERS.

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:

  1. prefix the file patterns with the subdir in the corresponding codeowners custom attribute

  2. 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.

  1. prefix file patterns in migrated codeowners custom attributes of module-a like module-a/PATTERN

  2. add !module-a/ as last rule to migrated root CODEOWNERS action to ignore the sub directory of module-a in this action