DevSensei: PR Workflow Automation

DevSensei is currently in beta phase and not yet available in the official Code Owners app release. If you are interested to join the beta, let us know.

What is DevSensei?

DevSensei is a new pull request workflow automation solution integrated into the Code Owners App.

It is for teams who want to:

reduce the overhead of working with pull requests
automate workflows in pull requests
follow and enforce team policies

Examples of such workflows are assigning reviewers or auto-merging pull requests based on configurable conditions.

How does it work?

DevSensei configuration is YAML-based.

Add a devsensei.yaml file to the root of your repository for the default branch, and DevSensei will automate your pull request workflow.

The configuration within the YAML file consists of a set of workflows. Each workflow is meant to automate specific tasks for the pull requests of your team. A workflow includes:

a name to identify the workflow
a set of conditions to be met for the actions of the workflow to be executed for a pull request
a set of actions to be executed when the conditions are met for a pull request

Here's an example devsensei.yaml that assigns Code Owners for a pull request introducing a new feature where the pull request is opened from a branch including the prefix feature/ with the destination branch being main or release:

workflows:
  - name: Add Code Owners
    conditions:
      - source~=feature/*
      - or:
          - destination=main
          - destination=release
    actions:
      - add-codeowners:
          rules: |
            *.js @@frontendDevs

What advantages has DevSensei compared to Code Owners?

Although DevSensei currently only supports one action (add-codeowners), we will add many more actions in the future to automate your pull request workflow.

At this stage, the main advantage of DevSensei compared to CODEOWNERS is that you can share common rules across repositories with includes to reduce duplication and improve maintenance costs.

Another advantage of devsensei.yaml is that common code parts can be shared with the help of the shared YAML section.

How can I migrate from Code Owners to DevSensei?

To start using DevSensei with your existing CODEOWNERS file, you have to

migrate your CODEOWNERS settings to their equivalents in devsensei.yaml. For the most part, copy everything except CODEOWNERS settings and custom groups from the CODEOWNERS file to the rules section of devsensei.yaml.
1. For the settings, use the alternatives from the add-codeowners action, see the reference guide.
2. For the custom groups, use the custom-groups section of add-codeowners.
push the devsensei.yaml file to the root directory in the default branch of your repository
when the app sees a devsensei.yaml file, it will use that instead of CODEOWNERS.

Note that DevSensei always reads the devsensei.yaml file from the default branch of your repository. This is in contrast to Code Owners CODEOWNERS file, where it is taken from the destination branch of a 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.

The format of the Code Owners rules is exactly the same, so you can copy paste that to the rules section of the add-codeowners action.

CODEOWNERS:

CODEOWNERS.destination_branch_pattern main
CODEOWNERS.destination_branch_pattern release/*
CODEOWNERS.toplevel.subdirectory_overrides enable
CODEOWNERS.toplevel.assignment_routing random 2
CODEOWNERS.toplevel.create_pull_request_comment disable
CODEOWNERS.toplevel.auto_unapprove_on_change enable
CODEOWNERS.source_branch_exclusion_pattern hotfix/*

@@@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:

shared:
  - custom-groups:
     MyDevs:
       - @PeterTheHacker
       - @PeterTheJavaExpert
       - ann@scala.lang 
       - @@JSDevs
      
workflows:
  - name: Add Code Owners
    conditions:
      - or:
        - destination=main
        - destination~=release/*
      - source~!=hotfix/*
    actions:
      - add-codeowners:
          auto-unapprove-on-change: true      
          assignment-routing:
            random: 2
          custom-groups:
            MyDevs: *MyDevs 
          rules: |
            *                       @PeterTheHacker
            *.java                  @PeterTheJavaExpert
            *.js                    @PaulTheJSGuru @@JSExperts
            "a/path with spaces/*"  docs@example.com
            !ci/playgrounds.yml
            src/components/**/*.js  @@MyDevs
            Check(@@MyDevs >= 2)

Which settings from Code Owners are not supported in DevSensei?

Code Owners feature	Why not supported / Alternative?

Code Owners feature	Why not supported / Alternative?
`CODEOWNERS.toplevel.create_pull_request_comment`	May be added later
`CODEOWNERS.toplevel.subdirectory_override`	Obsolete with `includes`

Is there IDE support for DevSensei configuration?

Yes, the app provides a YAML Schema for the devsensei.yaml file. Benefits:

Auto-completion of YAML keys
Basic validations (e.g. ensure that a workflow has actions)
Documentation of YAML elements within the editor
Showing code examples from the Spec as help

Download the YAML Schema from Bitbucket:

https://YOUR_BITBUCKET/rest/codeowners/1.0/devsensei/schema

Depending on your IDE, map that YAML Schema to files named devsensei.yaml.

IntelliJ IDEA & JetBrains IDE’s:

Go to IntelliJ IDEA (or other Jetbrains IDE) settings
Search for “JSON Schema Mappings”
Add a new mapping:
1. Name: DevSensei Schema file
2. Schema URL: https://YOUR_BITBUCKET/rest/codeowners/1.0/devsensei/schema
3. Schema version: JSON Schema version 7
4. File: devsensei.yaml

VS Code:

VS Code with the RedHat YAML plugin can either use an inline reference to the JSON Schema

or have a global mapping within the VS Code settings.json:

devsensei.yaml Language Reference

Workflows

Each workflow is meant to automate specific tasks for the pull requests of your team.

Attributes	Meaning

Attributes	Meaning
`name`	The unique name of the workflow
`overrides`	A workflow with the same name can be overridden in the main `devsensei.yaml` file. If so, the workflow object must have `overrides=true`. If not, then you will get a validation error for the duplicate names. `main.yaml`: `other.yaml`:
`conditions`	a set of conditions to be met for the actions of the workflow to be executed for a pull request
`actions`	a set of actions to be executed when the conditions are met for a pull request

Conditions

Conditions define the criteria that must be met so that the actions of a workflow are executed. They allow you to define which pull requests should be handled by DevSensei based on various criteria like the draft pull request status, source and destination branches, and more.

Syntax for a condition:

<attribute> <operator> <value>

The conditions are implicitly combined with and. More complex conditions can be created with and and or logical operators.

Example:

Attributes	Meaning

Attributes	Meaning
`source`	Source branch of pull request
`destination`	Destination branch of pull request
`draft`	Is it a draft pull request

Logical Operator	Meaning

Logical Operator	Meaning
`and`	Equals
`or`	Not equals

Operator	Meaning

Operator	Meaning
`=`	Equals
`!=`	Not equals
`~=`	Glob match
`~!=`	Glob negative match
`!` or `not`	Negate an attribute

Actions

add-codeowners:

Adds Code Owners as reviewers to a pull request.

Action field	Explanation	Example

Action field	Explanation	Example
`assignment-routing`	`random: n` reduce the number of Code Owners that are automatically assigned to a pull request. (opt-in) Currently, the only available method of assignment is at random.
`rules`	The Code Owners rules and merge checks. For existing `CODEOWNERS` users, just copy everything except the `CODEOWNERS settings` to the `rules` section.
`custom-groups`	define custom Code Owners groups
`auto-unapprove-on-change`	Remove approval if owned code changes

Includes

With includes, common Devsensei workflows can be shared both across repositories as well within projects in a monorepo.

To include a devsensei.yaml file from another repository, use this syntax:

Only repositories of the same Bitbucket project are supported:

When a plain YAML file path is specified, the included file is read from the same repository:

The files are read from the latest commit of the default branch
YAML Anchors will be resolved per file.
Only one level of includes are support (no recursion supported)

YAML Anchors

YAML Anchors are used to define reusable content in YAML files. They are resolved in the same file.

Example:

Anchors can be used for any content. For example, they can be used to define reusable custom user groups, or conditions.
Reference must only reference anchors in the same file. It is not possible to define an anchor in one file, and reference it from another file.
Anchors cannot contain the [, ], {, }, and , characters.
Anchors can be defined anywhere in the file, although we encourage to use the shared section at the top of the file for clarity.