In this page

Overview

Better Commit Policy for Jira provides a REST API for developers to implement custom use cases.

Examples:

  • Building custom hook scripts for the already supported Version Control Systems. When your system is covered, but you need some modifications in the hook's behavior.
  • Creating new hook scripts to adapt the app's verification functionality to unsupported Version Control Systems. When your system is not yet supported, but you want to leverage the app.
  • Developing maintenance scripts that do something in your repositories. For example, if you want to mass-install hook scripts to hundreds of repositories without using the UI.

The Better Commit Policy's REST API is a natural extension to Jira's core REST API. It uses the same semantics: you can authenticate to Jira and call REST methods the same exact way with both of those. Learn more about using the Jira REST API in the Jira Development documentation.

Please note that the set of the API methods is fairly limited at the moment, but we are open to requests to extend it.

Terminology

Since Better Commit Policy for Jira supports several Version Control Systems, each with its own concepts and terminology, we have to clarify the meaning of changeset in this documentation. In our terminology, a changeset consists of information about one or more commits, plus some additional metadata about the changeset itself.

REST API reference

/commit-policy

Description
 Returns the list of the existing commit policies.
Since
 1.3.0
URL
http://jira.mycompany.com/rest/commit-policy/1.0/commit-policy
Method
 GET
Returns
 Sample JSON response: 
[
	{
		"id": 1,
		"name": "ACME policy",
		"description": "This is the policy for all our projects at Acme, Inc.",
		"rejectionMessage": "You commit violates the ACME policy!",
		"enabled": true,
		"bypassMergeCommits": true,      /* since 3.0.0 */
		"bypassExistingCommits": true    /* since 3.0.0 */
	}
]

/commit-policy/{policy-id}/clone

Description
 Clones the commit policy with the passed ID by using a generated name and by copying its properties and rules.
Since
 3.4.0
URL
http://jira.mycompany.com/rest/commit-policy/1.0/commit-policy/5/clone
Method
 POST
Returns
 Sample JSON response: 
[
	{
		"id": 6,
		"name": "Copy of ACME Policy",   /* name cloned as "Copy of <original name>" */
		"description": "This is the policy for all our projects at Acme, Inc.",
		"rejectionMessage": "You commit violates the ACME policy!",
		"enabled": true,
		"bypassMergeCommits": true,
		"bypassExistingCommits": true
	}
]

/commit-policy/{policy-id}/verification

Description
 Verifies a changeset against a policy.
Since
 1.0.0
URL
http://jira.mycompany.com/rest/commit-policy/1.0/commit-policy/1/verification
Method
 POST
Returns
 Sample JSON request: 
{
	"tags": [
		{
			"name": "added-tag",
			"action": "a"
		}
	],
	"branches": [
		{
			"name": "deleted-branch",
			"action": "d"
		}
	],
	"commits": [
		{
			"id": "04c5ad0",
			"branch": "master",
			"isMerge": false,
			"isExisting": false,
			"userName": "johndoe <john.doe@acme.com>",
			"message": "Initial import",
			"files": [
				{
					"path": "foobar.txt",
					"action": "a"
				}
			]
		}
	],
	"vcs": "git",
	"diagnosticMode": false,
	"hookScriptVersion": "3.0.0",
	"hookScriptFeatures": [],
	"repositoryId": "c:\\git_repos\\super_duper_product"
}
Property Description
tags
(since 3.0.0)		 Optional. Array of changed tags. Only needs to be provided when one or more tag is created or deleted.
branches
(since 3.0.0)		 Optional. Array of changed branches. Only needs to be provided when one or more branch is created or deleted.
commits Array of the commits. Order: first item is the oldest commit, last item is the newest.
id Identifies the commit (its format depends on the VCS).
branch Identifies the branch on which the commit was made (its format depends on the VCS).
isMerge true if the commit is a merge commit.
isExisting
(since 3.0.0)		 false if the commit is not yet present in the (target) repository. Useful for server side hooks, but it is only taken into account by policies that are explicitly configured for that.
At the moment only our Git hooks support this flag and only policies created by app version 3.0.0 or later have this feature enabled by default.
Non-git hook scripts always use the default value false.
userName The author's username and the email address, as known by the VCS, in this format: userName <emailAddress>.
Some VCS system does not have an email address concept, those can omit the second part.
message Commit message.
files Optional. List of file paths and action that were made on them.
path Path from the repository root to the modified file.
action Optional. Possible values:
  • a: added
  • m: modified (applicable to paths only, tags and branches are never modified)
  • d: deleted
  • ?: unknown (default)
vcs Optional. Possible values:
  • git-server: git (server-side) (since 3.0.0)
  • git-local: git (client-side) (since 3.0.0)
  • git: git (server-side) (pre-3.0.0)
  • svn: Subversion
  • hg: Mercurial
  • ?: unknown (other)
diagnosticMode Optional. In this testing mode, the changeset is always accepted and the first commit is returned in JSON format. Defaults to false.
hookScriptVersion Optional. Unused at the moment, but will be used to track version matching between hook scripts and the serverside logic.
hookScriptFeatures
(since 3.0.0)		 Optional (filled automatically for our known hook scripts, based on version number). Contains the list of features the hook script implements:
  • SET_BRANCH: hook script provides valid branches field in the changeset
  • SET_TAG: hook script provides valid tags field in the changeset
  • SET_EXISTING_COMMIT: hook script provides isExisting flag for commits
repositoryId Optional. Identifies the repo (its format depends on the VCS). Unless having a better idea, the full filesystem path to the repo root is a good choice.
Sample JSON response: 
{
	"ok": false
	"rejectionMessageFormatted": "========================================================================
	REJECTED!
	========================================================================
	1.1 COMMIT [04c5ad0] on [master] Exactly one issue key must be mentioned in the commit message \"Initial import\"
	========================================================================
	REJECTED!
	========================================================================"
}

/hook-script/{vcs}/{os}/{policy-id}

Description
 Generates a hook script pack and returns its reference ID. See the next API call about using this ID.
Since
 1.0.0
URL
http://jira.mycompany.com/rest/commit-policy/1.0/hook-script/git/linux/1
Method
 POST
Returns
 Sample JSON response: 
{
	"packId": "58389b1dc1e55684c2804c561ba5e52d"
}

/hook-script/{hook-script-pack-id}

Description
 Downloads a previously generated hook script pack.
Since
 1.0.0
URL
http://jira.mycompany.com/rest/commit-policy/1.0/hook-script/58389b1dc1e55684c2804c561ba5e52d
Method
 GET
Returns
 Binary response, the hook script pack in ZIP format.

Questions?

Ask us any time.