CaC - Cheat Sheet | DevOpsSystems GmbH

Rule structure

A CaC file contains repository rules in a top-level rules section.

YAML

rules:
  - ...

Each entry in the rules list is a complete Process Guardian rule.

Anatomy of a rule

Each rule defines when it runs, what it validates, and under which conditions it applies.

YAML

rules:
  - title: "My rule"
    error: "Validation failed"
    hint: "Resolve the issue before merging"
    success: "Validation passed"
    description: "Optional rule description"
    enabled: true
    triggers: [PULL_REQUEST]
    target: [COMMITS, BRANCH]
    strategy: all

    checks:
      ...

    conditions:
      ...

Rule metadata

Field	Description
`title`	Human-readable name of the rule.	Required
`error`	Message shown when the rule fails.	Required
`hint`	Additional guidance shown alongside a failure.
`success`	Optional message shown when the rule passes.
`description`	Optional documentation text for the rule.
`enabled`	Enables or disables the rule. Defaults to `true`.
`triggers`	Triggers define which lifecycle events execute the rule.	Required
`target`	Targets define which artifacts are inspected by a rule.	Required
`checks`	Checks define what is validated when the rule runs.	Required

Triggers

Triggers define which lifecycle events execute the rule.

Trigger	Description
`PULL_REQUEST`	Executes the rule during pull request validation.
`COMMIT`	Executes the rule during commit validation through the Validation API.
`PUSH`	Executes the rule during push validation through the Validation API.

Important: Commit and Push validation are available through the Validation API, for example using local Git hooks, CI/CD pipelines, or custom integrations. Bitbucket Cloud does not currently provide a server-side pre-receive API for blocking pushes directly.

Targets

Targets define which artifacts are inspected by a rule.

Target	Description
`COMMITS`	Validates all commits in the validation scope.
`COMMIT`	Validates all commits but only one needs to be valid
`BRANCH`	Validates the source branch name.
`TITLE`	Validates the pull request title.
`DESCRIPTION`	Validates the pull request description.

Target strategy

The strategy field defines how multiple targets are evaluated.

Strategy	Description
`all`	All selected targets must satisfy the rule.
`one`	At least one selected target must satisfy the rule.

Checks

Checks define what is validated when the rule runs.

A rule can contain issue checks, naming checks, or both.

YAML

checks:
  issue:
    ...
  naming:
    ...

Issue checks

Issue checks validate Jira-related requirements, such as issue key presence, issue key consistency, and JQL compliance.

YAML

checks:
  issue:
    key: true
    consistency: true
    jql: "status = 'In Progress'"

Issue key check

The key check validates that issue keys are present and can be resolved in Jira.

Supported forms:

YAML

key: true
key: all
key: one
key:
  enabled: true
  strategy: all

Strategy	Description
`all`	All detected issue keys in the selected target must be valid Jira issues.
`one`	At least one detected issue key in the selected target must be a valid Jira issue.

Issue consistency

The consistency check validates that issue keys across the configured targets reference the same Jira issue.

YAML

consistency: true

This is useful when commits, branches, and pull request fields are expected to refer to the same work item.

JQL check

The jql check validates detected Jira issues against a JQL query.

Supported forms:

YAML

jql: "status = 'In Progress'"
jql:
  enabled: true
  query: "status = 'In Progress'"
  strategy: all

Strategy	Description
`all`	All detected issue references in the selected target must match the configured JQL query.
`one`	At least one detected issue reference in the selected target must match the configured JQL query.

Naming checks

Naming checks validate branch names, commit messages, pull request titles, and pull request descriptions using regular expressions.

YAML

checks:
  naming:
    branch:
      pattern:
        - "^(feature|bugfix|hotfix)/[A-Z]+-\\d+.*"
      strategy: all
    commit:
      pattern:
        - "^[A-Z]+-\\d+.*"
      strategy: all
    pullRequest:
      title:
        pattern:
          - "^[A-Z]+-\\d+.*"
        strategy: all
      description:
        pattern:
          - ".*Closes [A-Z]+-\\d+.*"
        strategy: all

Naming check options

Field	Description
`branch`	Validates the source branch name.
`commit`	Validates commit messages.
`pullRequest.title`	Validates the pull request title.
`pullRequest.description`	Validates the pull request description.

Each naming option supports either a shorthand string or an expanded object.

Shorthand syntax

YAML

checks:
  naming:
    branch: "(feature|bugfix|hotfix)/[A-Z]+-\\d+.*"

Strategy	Description
`all`	All configured regex patterns must match.
`one`	At least one configured regex pattern must match.

Conditions

Conditions define whether a rule should run.

Currently, the preferred CaC format supports pull request and branch conditions.

YAML

conditions:
  branch:
    include:
        pattern: ["^feature/.*"]
        strategy: one
  pullRequest:
    destination:
      include:
        pattern: ["^main$", "^release/.*"]
        strategy: one

Pull request condition

The pull request condition can restrict rule execution based on:

destination branch

Each branch condition can define include and exclude rules.

YAML

conditions:
  pullRequest:
    destination:
      include:
        pattern: ["^main$", "^release/.*"]
        strategy: one
      excluce:
        pattern: ["^feature/.*", "^bug/.*"]
        strategy: one

Branch condition

Pull request condition can restrict rule execution based on:

branch/source-branch

Each branch condition can define include and exclude rules.

YAML

conditions:
  branch:
      include:
       pattern: ["^feature/.*", "^bug/.*"]
        strategy: one
      exclude:
        pattern: ["^main$", "^release/.*"]
        strategy: one

Include and exclude

Condition	Description
`include`	The rule is executed only if the branch matches the include pattern.
`exclude`	The rule is skipped if the branch matches the exclude pattern, unless an include condition takes precedence.

Pattern strategy

Strategy	Description
`all`	All configured patterns must match.
`one`	At least one configured pattern must match.

For exclude conditions, the default strategy is one.

Example configurations

Jira issue key validation

YAML

rules:
  - title: "Jira issue keys"
    error: "One or more commits lack a valid Jira issue key."
    hint: "Include a valid Jira issue ID like 'ABC-123' in each commit message."
    success: "All commits reference valid Jira issues."
    target: [COMMITS, BRANCH]
    checks:
      issue:
        key: true
        consistency: true

Branch naming convention

YAML

rules:
  - title: "Branch naming"
    error: "Branch name does not follow the required format."
    hint: "Use feature/ABC-123-description"
    target: [BRANCH]
    checks:
      naming:
        branch:
          pattern:
            - "(feature|bugfix|hotfix|release)/[A-Z]+-\\d+.*"
          strategy: all

JQL validation

YAML

rules:
  - title: "Issue status validation"
    error: "Issue is not in a valid review state."
    hint: "Move the Jira issue to 'In Review'."
    success: "The issue is in a valid review state."
    target: [COMMITS, BRANCH, TITLE]
    checks:
      issue:
        jql:
          query: "status in ('In Review', 'Ready for Merge')"
          strategy: all

Feature freeze for release branches

YAML

rules:
  - title: "Feature Freeze"
    error: "This pull request includes a new functionality but targets a release branch."
    hint: "Please target a development branch for the pull request."
    success: "Only allowed issue types are linked to this release pull request."
    triggers: [PULL_REQUEST]
    target: [COMMITS, BRANCH, TITLE, DESCRIPTION]
    strategy: all
    description: "Prevents merging feature-related changes into release branches."
    checks:
      issue:
        jql: "issueType = Bug"
    conditions:
      pullRequest:
        destination:
          include:
            pattern: ["release/.*"]
            strategy: all

Important notes

If no configuration file exists, no CaC rules are executed
Rule changes become part of the repository history
Different branches can use different rule configurations

Key takeaway

Configuration as Code enables versioned, reviewable, and branch-specific compliance configurations directly inside the repository. It allows teams to define triggers, targets, checks, and conditions in YAML while reusing the same validation model that is available in the UI.