Pull request description conventions

In this page

Overview

This page provides ready-made solutions for enforcing common pull request description 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 description minimum length

Use the pull-request.description.pattern parameter with the regex below to require at least 10 character long pull request descriptions.

pull-request:
  description:
    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 description

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

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

The leading (?s) in the regex supports multi-line pull request descriptions. Change FOO to your required project key.

Require a work item key from specific projects in the pull request description

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

The leading (?s) in the regex supports multi-line pull request descriptions. Change FOO and BAR to your required project keys.

Require a work item key from specific work items in the pull request description

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

The leading (?s) in the regex supports multi-line pull request descriptions. Change FOO-1 and such to your required project keys.

Require a work item key in a specific status in the pull request description

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

The leading (?s) in the regex supports multi-line pull request descriptions. 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 description

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

The leading (?s) in the regex supports multi-line pull request descriptions. 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 description

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:
  description:
    pattern: (?s)FOO-\d+.*
    work-item:
      jql: project = FOO and statusCategory = "In progress"
      count: "1+"
      non-matching: "reject"

The leading (?s) in the regex supports multi-line pull request descriptions. Change FOO to your required project key.

Require a work item key assigned to the Git committer in the pull request description

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

The leading (?s) in the regex supports multi-line pull request descriptions. 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 description

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:
  description:
    pattern: (?s)FOO-\d+.*
    work-item:
      jql: project = FOO and (assignee = "$commit.author" or project in projectsLeadByUser("$commit.author"))
      count: "1+"
      non-matching: "reject"

The leading (?s) in the regex supports multi-line pull request descriptions. 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 description

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:
  description:
    pattern: (?s)FOO-\d+.*
    work-item:
      jql: project = FOO and (assignee = "$commit.author" or "Reviewer" = "$commit.author")
      count: "1+"
      non-matching: "reject"

The leading (?s) in the regex supports multi-line pull request descriptions. 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 description

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

The leading (?s) in the regex supports multi-line pull request descriptions. 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 description

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

The leading (?s) in the regex supports multi-line pull request descriptions. 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 description

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

The leading (?s) in the regex supports multi-line pull request descriptions. Change FOO to your required project key. Change "Web UI" to your required component.

Other conditions for work item keys in the pull request description

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