Top-Level Properties

A devsensei.yaml file has a few reserved top-level properties:

Share Configuration with Includes 🔬

With includes, common Devsensei workflows can be shared both across repositories as well within subdirectories. For a monorepo approach, see the dedicated section below.

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

includes:
- repository: shared-configs
  file: project-devsensei.yaml

Only repositories of the same Bitbucket project are supported.

The Bitbucket users require READ access to the repository with the shared configuration. Otherwise users will get permission issues, because they cannot access the required configuration.

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

includes:
- common/devsensei.yaml

• The files are read from the latest commit of the default branch

• Only one level of includes are support (no recursion supported)

Monorepo support with Directory Includes 🔬

SINCE 9.8

The includes attribute also has a special mode for monorepo applications, called “directory include”.

To include a subdirectory to be considered as a sub-project on its own, use this syntax:

includes:
- directory: folder/of/app-1
- directory: folder/of/app-2

Including a directory with this syntax will have the following effects:

• it will read the devsensei.yaml file in the included directory (the configuration is invalid if none is found)

• in the DevSensei UI, workflow names will be prepended by the directory path. For example, a workflow called “Code Owners” in folder/of/app-1 will be named fold/of/app-1/Code Owners. This is a purely cosmetic consideration.

• it will only run workflows in the included devsensei.yaml file if the pull request affects at least one file within that directory (or subdirectories thereof). User-defined workflow conditions are otherwise applied as normal.
  Note that you can opt-out of this restriction for a particular workflow by using the ignore-directory-scope: true attribute on a specific workflow

• all affected file paths will be relative to the included directory, and not from the repository root.
  Example: suppose the pull request modifies the files foo/x.txt and bar/y.txt, and the configuration included the directory foo via

  YAML

  includes:
  - directory: foo
  

  In that case, workflows in foo will see the paths x.txt and ../bar/y.txt.

• In particular, for Code Owners definitions, don’t prefix every rule by the path to the included directory.

• An included directory is allowed to recursively include another sub-directory in turn (to a limit of 10 nested includes). In that case, the behaviour is the same as if the sub-directory was directly included from the root devsensei.yaml file.

Sharing Parts of the Configuration with YAML Anchors 🔬

Use YAML Anchors to define reusable content in the same YAML file.

Example showing how to share conditions across workflows:

shared:
  conditions:
    - &non-hotfix-to-release-branch
      - source~!=hotfix/*
      - destination~=release/*

workflows:
  - name: comment
    conditions: *non-hotfix-to-release-branch
    actions:
      - add-comment:
          content: |
            Hotfix branch expected as source branch when merging into release branches.
            Source was ${source}.
  - name: codeowners
    custom-attributes:
      codeowners:
        rules: |
          *.js  @peter
    conditions: *non-hotfix-to-release-branch
    actions:
      - add-reviewers:
          members: codeowners

• Anchors can be used for any content. For example, to define reusable custom user groups, or conditions.

• Reference must reference anchors in the same file. It is not possible to define an anchor in one file, and reference it from another file.

• Anchor names 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 and easier maintenance.

Configuration of the condition checks for time-dependent attributes 🔬

Workflow conditions involving time-dependent attributes (such as the age of the Pull Request) are re-evaluated every hour (in addition to any other change in the pull request). This behavior can be changed by specifying the schedule at the root of the devsensei.yaml file, under the run-schedule property.

Example:

run-schedule:
  every: 30 minutes