In this page
References
Field reference
commit-policy
vcs-connection
*.rejection-message
commit.message
commit.author
commit.type
pull-request.title
pull-request.description
pull-request.source-branch
pull-request.destination-branch
pull-request.commit
setting
JQL variable reference
How to use JQL variables?
How-tos
How to use quotation marks in field values?
How to use JQL-related fields together?
What is ".commitpolicy.yml"?
Commit policies are configured by a human-readable YAML format configuration file. This file must be placed in the root of the Git repository and must be named .commitpolicy.yml.
In summary, the file defines the rules used to validate commits and pull requests in the repository, as well as additional settings that configure how the rules are evaluated.
Here is a configuration example that require a 5+ characters long commit message starting with a valid DEMO work item key:
commit-policy:
name: "DEMO commit policy"
description: "Compliance rules for the DEMO project."
vcs-connection:
id: "ad9bc1d2-53fe-42b5-ab13-b5eafb743db1"
commit:
rejection-message: "Write a 5+ char long commit message, starting with a valid DEMO work item key!"
message:
pattern: (?s)DEMO-\d+ [A-Z0-9](\S|\S\s*){4,}
work-item:
jql: 'project=DEMO and statusCategory="In Progress" and assignee="$commit.author"'
count: "1+"
strict: true
References
This section provides a reference for the fields and JQL variables that can be used in the configuration file.
Field reference
Although the YAML language uses multiple lines and indentation to express structure, this reference uses an alternative, more compact dot notation. When you see the field name commit-policy.name with the value "Hello world" in the reference, it actually means a section like this in the configuration file:
commit-policy: name: "Hello world"
Just break the field name at the . characters and indent by two spaces. That's it!
commit-policy
These fields configure metadata related to the commit policy. They are for display purposes only. They don't affect any logic.
| Field name | Value (example) | Notes |
|---|---|---|
| commit-policy.name | "DEMO commit policy" | For display purpose only. |
| commit-policy.description | "Compliance rules for the DEMO project." | For display purpose only. Use Unicode emojis to make it more fun. |
vcs-connection
This field configures the secure connection between the Jira Cloud site and the Bitbucket Cloud workspace.
| Field name | Value (example) | Notes |
|---|---|---|
| vcs-connection.id | "ad9911d2-56fe-42b5-ab13-b5e0fb883db1" | JQL queries will be executed against this Jira Cloud site. |
*.rejection-message
These fields configure the custom rejection messages to show when a subject of a given type violates the commit policy. Use them to explain the requirements for the user. Showing an example is a good practice!
| Field name | Value (example) | Notes |
|---|---|---|
| pull-request.rejection-message | "Write a 5+ char long pull request title and a 10+ char long pull request description!" | Shown for the pull requests that violate the policy. |
| commit.rejection-message | "Write a 5+ char long commit message, starting with a valid DEMO work item key! Example: \"DEMO-123 Fix for memory leak\"" | Shown for the commits that violate the policy. |
commit.message
These fields configure the conditions that commit messages must satisfy in order for the commit to be accepted. You can enforce a specific message format or length using regular expressions, require references to valid work items, and control how many and which work item keys must be included.
| Field name | Value (example) | Notes |
|---|---|---|
| commit.message.pattern | (?s)DEMO-\d+ [A-Z0-9](\S|\S\s*){4,} |
Every commit message must match this regular expression.
Require the minimum length, the proper format and linked work item keys. 💡 See the commit message recipes. |
| commit.message.work-item.jql | project=DEMO and statusCategory="In Progress" and assignee="$commit.author" or reporter="$commit.author" |
Work item keys in the commit message must be in the search results of this JQL query.
Require work items in a specific project, with a specific assignee, in a specific status, in the current sprint and similar. Use JQL variables for dynamic behavior. 💡 See the JQL recipes. |
| commit.message.work-item.count |
Examples:
|
Every commit message must contain exactly one ("1"), one or more ("1+"), specific number ("3"), specific number or more ("3+") work item keys. |
| commit.message.work-item.non-matching |
Options:
|
When set to "reject", every commit message that includes non-matching or non-existing work item keys will be strictly rejected.
With "accept-existing", only non-existing work item keys are rejected.
With "accept", all additional work item keys are accepted without further checks. Use "reject" if unsure. (See how to use it with previous two.) |
| commit.message.skip-pattern | "#noverify" |
Checks will be skipped for the commit if the commit message matches this regular expression.
Skip old commits, commits by external contributors, automatic commits from the CI/CD system, and similar. (Default: write "#skipcheck" to the commit message.) |
commit.author
This field configures whether the commits created by certain authors should be skipped. You can skip old commits, commits by external contributors, automatic commits from the CI/CD system, and similar. You can also use it to select exempt users (e.g. development team leads) with extended flexibility.
| Field name | Value (example) | Notes |
|---|---|---|
| commit.author.skip-pattern | "john" | Checks will be skipped for the commit if the commit author matches this regular expression. |
commit.type
These fields configure whether certain types of commits should be skipped. All permutations are valid.
| Field name | Value (example) | Notes |
|---|---|---|
| commit.type.skip-ordinary | false |
When turned on, the policy skips the checks for ordinary (non-merge) commits.
It is useful if ordinary commits are considered "less important" in your Git workflow. (Default: off.) |
| commit.type.skip-merge | true |
When turned on, the policy skips the checks for merge commits.
It is useful if merge commits are considered "administrative only" in your Git workflow. (Default: on.) |
pull-request.title
These fields configure the conditions that pull request titles must satisfy in order for the pull request to be accepted. The policy can enforce a specific title format using a regular expression, require one or more valid work item keys, and control how non-matching or non-existing work item keys are handled.
| Field name | Value (example) | Notes |
|---|---|---|
| pull-request.title.pattern | (?s)DEMO-\d+ [A-Z0-9](\S|\S\s*){4,} |
Every pull request title must match this regular expression.
Require the minimum length, the proper format and linked work item keys. 💡 See the pull request title recipes. |
| pull-request.title.work-item.jql | project=DEMO and statusCategory="In Progress" and assignee="$pull-request.author" or reporter="$pull-request.author" |
Work item keys in the pull request title must be in the search results of this JQL query.
Require work items in a specific project, with a specific assignee, in a specific status, in the current sprint and similar. Use JQL variables for dynamic behavior. 💡 See the JQL recipes. |
| pull-request.title.work-item.count |
Examples:
|
Every pull request title must contain exactly one ("1"), one or more ("1+"), specific number ("3"), specific number or more ("3+") work item keys. |
| pull-request.title.work-item.non-matching |
Options:
|
When set to "reject", every pull request title that includes non-matching or non-existing work item keys will be strictly rejected.
With "accept-existing", only non-existing work item keys are rejected.
With "accept", all additional work item keys are accepted without further checks. Use "reject" if unsure. (See how to use it with previous two.) |
| pull-request.title.skip-pattern | "#noverify" |
Checks will be skipped for the pull request if the pull request title matches this regular expression.
(Default: write "#skipcheck_pr" to the pull request title.) |
pull-request.description
These fields configure the conditions that pull request descriptions must satisfy in order for the pull request to be accepted. The policy can enforce a specific format using a regular expression, require one or more valid work item keys, and control how non-matching or non-existing work item keys are handled.
| Field name | Value (example) | Notes |
|---|---|---|
| pull-request.description.pattern | (?:\S|\S\s*){9,} |
Every pull request description must match this regular expression.
Require the minimum length, the proper format and linked work item keys. 💡 See the pull request description recipes. |
| pull-request.description.work-item.jql | project=DEMO and statusCategory="In Progress" and assignee="$pull-request.author" or reporter="$pull-request.author" |
Work item keys in the pull request description must be in the search results of this JQL query.
Require work items in a specific project, with a specific assignee, in a specific status, in the current sprint and similar. Use JQL variables for dynamic behavior. 💡 See the JQL recipes. |
| pull-request.description.work-item.count |
Examples:
|
Every pull request description must contain exactly one ("1"), one or more ("1+"), specific number ("3"), specific number or more ("3+") work item keys. |
| pull-request.description.work-item.non-matching |
Options:
|
When set to "reject", every pull request description that includes non-matching or non-existing work item keys will be strictly rejected.
With "accept-existing", only non-existing work item keys are rejected.
With "accept", all additional work item keys are accepted without further checks. Use "reject" if unsure. (See how to use it with previous two.) |
| pull-request.description.skip-pattern | "#noverify" |
Checks will be skipped for the pull request if the pull request description matches this regular expression.
(Default: write "#skipcheck_pr" to the pull request description.) |
pull-request.source-branch
These fields configure the conditions that the source branch name of a pull request must satisfy in order for the pull request to be accepted. The policy can enforce a specific naming pattern using a regular expression, require one or more valid work item keys, and control how non-matching or non-existing work item keys are handled.
| Field name | Value (example) | Notes |
|---|---|---|
| pull-request.source-branch.pattern | (?s)feature/DEMO-\d+ [A-Z0-9]{4,} |
Every pull request source branch name must match this regular expression.
Require the minimum length, the proper format and linked work item keys. 💡 See the pull request source branch name recipes. |
| pull-request.source-branch.work-item.jql | project=DEMO and statusCategory="In Progress" and assignee="$pull-request.author" or reporter="$pull-request.author" |
Work item keys in the pull request source branch name must be in the search results of this JQL query.
Require work items in a specific project, with a specific assignee, in a specific status, in the current sprint and similar. Use JQL variables for dynamic behavior. 💡 See the JQL recipes. |
| pull-request.source-branch.work-item.count |
Examples:
|
Every pull request source branch name must contain exactly one ("1"), one or more ("1+"), specific number ("3"), specific number or more ("3+") work item keys. |
| pull-request.source-branch.work-item.non-matching |
Options:
|
When set to "reject", every pull request source branch name that includes non-matching or non-existing work item keys will be strictly rejected.
With "accept-existing", only non-existing work item keys are rejected.
With "accept", all additional work item keys are accepted without further checks. Use "reject" if unsure. (See how to use it with previous two.) |
| pull-request.source-branch.skip-pattern | "#noverify" |
Checks will be skipped for the pull request if the pull request source branch name matches this regular expression.
(Default: write "#skipcheck" to the pull request source branch name.) |
pull-request.destination-branch
These fields configure the conditions that the target branch name of a pull request must satisfy in order for the pull request to be accepted. The policy can enforce a specific naming pattern using a regular expression, require one or more valid work item keys, and control how non-matching or non-existing work item keys are handled.
| Field name | Value (example) | Notes |
|---|---|---|
| pull-request.destination-branch.pattern | (?s)feature/DEMO-\d+ [A-Z0-9]{4,} |
Every pull request destination branch name must match this regular expression.
Require the minimum length, the proper format and linked work item keys. 💡 See the pull request destination branch name recipes. |
| pull-request.destination-branch.work-item.jql | project=DEMO and statusCategory="In Progress" and assignee="$pull-request.author" or reporter="$pull-request.author" |
Work item keys in the pull request destination branch name must be in the search results of this JQL query.
Require work items in a specific project, with a specific assignee, in a specific status, in the current sprint and similar. Use JQL variables for dynamic behavior. 💡 See the JQL recipes. |
| pull-request.destination-branch.work-item.count |
Examples:
|
Every pull request destination branch name must contain exactly one ("1"), one or more ("1+"), specific number ("3"), specific number or more ("3+") work item keys. |
| pull-request.destination-branch.work-item.non-matching |
Options:
|
When set to "reject", every pull request destination branch name that includes non-matching or non-existing work item keys will be strictly rejected.
With "accept-existing", only non-existing work item keys are rejected.
With "accept", all additional work item keys are accepted without further checks. Use "reject" if unsure. (See how to use it with previous two.) |
| pull-request.destination-branch.skip-pattern | "#noverify" |
Checks will be skipped for the pull request if the pull request destination branch name matches this regular expression.
(Default: write "#skipcheck" to the pull request destination branch name.) |
pull-request.commit
These fields configure whether complete pull requests should be skipped. The policy can skip checks if any commit within the pull request has a message or author matching the set regular expression.
| Field name | Value (example) | Notes |
|---|---|---|
| pull-request.commit.message.skip-pattern | #skipcheck_all | Checks will be skipped for the pull request if it contains at least one commit with the commit message matching this regular expression. |
| pull-request.commit.author.skip-pattern | john | Checks will be skipped for the pull request if it contains at least one commit with the author matching this regular expression. |
setting
These fields configure additional options that apply across the policy. You can customize the regular expression used to extract work item keys from commit messages, enable "dry run" mode to surface violations without blocking commits, and control whether technical errors during validation should cause a rejection.
| Field name | Value (example) | Notes |
|---|---|---|
| setting.work-item-key-pattern | (?<=\s|\W|^)[A-Z][A-Z\d]*\-\d+(?=\s|\W|$) |
Regular expression to extract work item keys from commit messages.
You can use it to allow or disallow work item keys in lowercase, uppercase, mixed case, for example. (See recipes.) (Default: all texts in the XYZ-123 format will match.) |
| setting.dry-run | false |
When turned on, the policy accepts the commit that violates it, but displays the violations.
You can use it for testing purposes or for suggesting, but not enforcing best practices. (Default: off.) |
| setting.reject-on-error | true |
When turned on, the policy rejects the commit if it can't be checked due to technical problems (e.g. when Jira is down). (Default: on.) |
JQL variable reference
JQL variables are simple dynamic placeholders that can be used in JQL query type field values. They are represented in the format $variable.name. They will be substituted with the actual values before the JQL search is executed.
| Variable | Description |
|---|---|
| $commit.author | Author of the Git commit. Resolves to an alphanumeric Atlassian account ID. |
| $pull-request.author | Author of the pull request. Resolves to an alphanumeric Atlassian account ID. |
How to use JQL variables?
As the resolved value is inserted "as is", always wrap the variable name with quotes:
project=DEMO and statusCategory="In Progress" and assignee="$pull-request.author" or reporter="$pull-request.author"
With this JQL query, the policy will only accept those pull requests where the pull request title links to a work item in the DEMO project, the status category of the work item is "In Progress", and either the assignee or the reporter of the work item is the pull request author.
Notes:
- The $commit.author variable might remain unresolved if the author's name or email address cannot be matched to a valid Atlassian account. (It could happen when you "import" commits from an external source.)
- The $pull-request.author variable will always be resolved to a valid Atlassian account, since only authenticated users can create pull requests in Bitbucket Cloud.
- The JQL queries are always executed on behalf of the pull request creator. Remember this when using JQL functions such as currentLogin() or currentUser().
How-tos
How to use quotation marks in field values?
We recommend wrapping field values in single or double quotes to avoid parsing errors, especially when dealing with strings that contain special characters, leading zeros, or reserved keywords. Be sure to escape any quote characters that appear within the string itself.
Examples:
// note the escaped double-quote within the string! "Start the commit message with a valid DEMO work item key! Example: \"DEMO-123 Fix for mem leak\"" // note the escaped single-quote within the string! 'Start the commit message with a valid DEMO work item key! Example: \'DEMO-123 Fix for mem leak\''
However, for improved readability and to reduce the need for escaping, it may be preferable to omit quotes in certain cases, such as JQL query strings.
Examples:
// with quotes (harder to read) "project=DEMO and statusCategory=\"In Progress\"" // without quotes (equivalent, but easier to read) project=DEMO and statusCategory="In Progress"
How to use JQL-related fields together?
The three JQL related fields (jql, count, and nonmatching) work together when checking the work items referenced in commit messages, for example. Different combinations implement slightly different strategies. The table below provides a clear guide on the possible strategies.
| When to use? | JQL | Count | Non-matching |
|---|---|---|---|
| Require exactly N existing work item keys. Ignore all others. | empty | N | accept |
|
Require exactly N existing work item keys. Reject all others. (It is the same as the next one, because there are no work items that don't match the JQL, but exist. Tip: use "reject" as that is more intuitive.) |
empty | N | accept-existing |
| Require exactly N existing work item keys. Reject all others. | empty | N | reject |
| Require N or more existing work item keys. Ignore all others. | empty | N+ | accept |
|
Require N or more existing work item keys. Reject all others. (It is the same as the next one, because there are no work items that don't match the JQL, but exist. Tip: use "reject" as that is more intuitive.) |
empty | N+ | accept-existing |
| Require N or more existing work item keys. Reject all others. | empty | N+ | reject |
| Require exactly N matching work item keys. Ignore all others. | non-empty | N | accept |
| Require exactly N matching work item keys. Ignore other existing ones. Reject non-existing ones. | non-empty | N | accept-existing |
| Require exactly N matching work item keys. Reject all others. | non-empty | N | reject |
| Require N or more matching work item keys. Ignore all others. | non-empty | N+ | accept |
| Require N or more matching work item keys. Ignore other existing ones. Reject non-existing ones. | non-empty | N+ | accept-existing |
| Require N or more matching work item keys. Reject all others. | non-empty | N+ | reject |
Questions?
Ask us any time.