Pull request destination branch conventions

In this page

Overview

This page provides ready-made solutions for enforcing common pull request destination branch name related conventions. Each example includes a YAML configuration snippet you can add to your own .commitpolicy.yml file and customize.

💡 Even if a recipe doesn't exactly fit your needs, it can still point you in the right direction!

Require pull request destination branch name minimum length

Use the pull-request.destination-branch.pattern parameter with the regex below to require at least 10 character long pull request destination branch names.

pull-request:
  destination-branch:
    pattern: (?:\S|\S\s*){10,}

Change the 10 in the regex to your required minimum length. Note that whitespace characters are excluded.

Require a work item key from a specific project in the pull request destination branch name

Use the pull-request.destination-branch.pattern parameter with the regex below to require developers to start the pull request destination branch name with "FOO-123 ...", a properly formatted work item key. Also use the pull-request.destination-branch.work-item.* parameter group with the JQL query below to ensure that only valid work items are accepted.

pull-request:
  destination-branch:
    pattern: (?s)FOO-\d+.*
    work-item:
      jql: project = FOO
      count: "1+"
      non-matching: "reject"

Change FOO to your required project key.

Require a work item key from specific projects in the pull request destination branch name

pull-request:
  destination-branch:
    pattern: (?s)(?:FOO|BAR)-\d+.*
    work-item:
      jql: project in (FOO, BAR)
      count: "1+"
      non-matching: "reject"

Change FOO and BAR to your required project keys.

Require a work item key from specific work items in the pull request destination branch name

pull-request:
  destination-branch:
    pattern: (?s)FOO-\d+.*
    work-item:
      jql: key in ("FOO-1", "FOO-2", "FOO-3")
      count: "1+"
      non-matching: "reject"

Change FOO-1 and such to your required project keys.

Require a work item key in a specific status in the pull request destination branch name

pull-request:
  destination-branch:
    pattern: (?s)FOO-\d+.*
    work-item:
      jql: project = FOO and status = "In progress"
      count: "1+"
      non-matching: "reject"

Change FOO to your required project key. Change "In progress" to your required status (keep the quotes!).

Require a work item key in specific statuses in the pull request destination branch name

pull-request:
  destination-branch:
    pattern: (?s)FOO-\d+.*
    work-item:
      jql: project = FOO and status in ("In progress", "In review", "In testing")
      count: "1+"
      non-matching: "reject"

Change FOO to your required project key. Change "In progress" and such to your required statuses (keep the quotes!).

Require a work item key in a specific status category in the pull request destination branch name

This is a shorter version of the previous recipe. The previous recipe has a problem: if you have several statuses that all are in the same status category ("To do", "in progress" or "Done"), it is cumbersome to enumerate them. To fix this, this recipe relies on the status category instead of the individual statuses.

pull-request:
  destination-branch:
    pattern: (?s)FOO-\d+.*
    work-item:
      jql: project = FOO and statusCategory = "In progress"
      count: "1+"
      non-matching: "reject"

Change FOO to your required project key.

Require a work item key assigned to the Git committer in the pull request destination branch name

pull-request:
  destination-branch:
    pattern: (?s)FOO-\d+.*
    work-item:
      jql: project = FOO and assignee = "$commit.author"
      count: "1+"
      non-matching: "reject"

Change FOO to your required project key. $commit.author is a JQL variable which will be resolved to the Git committer.

Require a work item key assigned to the Git committer or the project lead in the pull request destination branch name

This is an extended version of the previous recipe. The previous recipe has a problem: if another developer reviewed the commit, they couldn't add follow-up changes using the same work item, because it was assigned to the original developer. To fix this, this recipe also allows project leads to commit against any work item in their projects.

pull-request:
  destination-branch:
    pattern: (?s)FOO-\d+.*
    work-item:
      jql: project = FOO and (assignee = "$commit.author" or project in projectsLeadByUser("$commit.author"))
      count: "1+"
      non-matching: "reject"

Change FOO to your required project key. $commit.author is a JQL variable which will be resolved to the Git committer.

Require a work item key assigned to or reviewed by the Git committer in the pull request destination branch name

This is a flexible version of the previous recipe. The previous recipe has a limitation: only project leads could commit to the work items in addition to the assignee. To remove this limitation, add a user picker type custom field called "Reviewer" (or "Reviewers" if you allow multiple users) and hand-pick the reviewer for each work item!

pull-request:
  destination-branch:
    pattern: (?s)FOO-\d+.*
    work-item:
      jql: project = FOO and (assignee = "$commit.author" or "Reviewer" = "$commit.author")
      count: "1+"
      non-matching: "reject"

Change FOO to your required project key. Change "Reviewer" to the name of your user picker custom field (keep the quotes!). $commit.author is a JQL variable which will be resolved to the Git committer.

Require a work item key from the current sprint in the pull request destination branch name

pull-request:
  destination-branch:
    pattern: (?s)FOO-\d+.*
    work-item:
      jql: project = FOO and type = Story and sprint in openSprints()
      count: "1+"
      non-matching: "reject"

Change FOO to your required project key. Change Story to your required work item type.

Require a work item key assigned to a specific fix version in the pull request destination branch name

pull-request:
  destination-branch:
    pattern: (?s)FOO-\d+.*
    work-item:
      jql: project = FOO and fixVersion = "1.2.3-beta"
      count: "1+"
      non-matching: "reject"

Change FOO to your required project key. Change "1.2.3-beta" to your required fix version.

Require a work item key related to a specific component in the pull request destination branch name

pull-request:
  destination-branch:
    pattern: (?s)FOO-\d+.*
    work-item:
      jql: project = FOO and component = "Web UI"
      count: "1+"
      non-matching: "reject"

Change FOO to your required project key. Change "Web UI" to your required component.

Other conditions for work item keys in the pull request destination branch name

In addition to the recipes we've covered, there are many other possible requirements. For example, you might need to enter work item keys that have subtasks, linked work items, or fix versions following a specific pattern.

As a general rule, you can enforce any constraint on work item keys that can be expressed as a JQL query. JQL queries use built-in functions and fields. Remember, third-party apps can also extend JQL capabilities with additional functions, and you can also use those in your commit policies!

For more information, see the following resources:

JQL search (advanced search in general)
Built-in JQL functions
Built-in JQL fields
Third party apps with additional JQL functions

Questions?

Ask us any time.

Better Commit Policy Connector for Bitbucket Cloud

Useful links

Inspiration

Resources

Tutorials

Documentation