« Hooks & API

Commits

Last Updated: March 25, 2019

Call the Get Commits API to obtain commit information associated with an issue.

v2.11.0+ The repository id and repository name field in the response result was implemented.

Get Commits REST API
url
/rest/gitplugin/1.0/issues/{issueKey}/commits
method
GET
parameters
{issuekey} String. Required.
This is the Jira Issue Key - a concatenation of Project key and Issue number. It must contain a dash ("-"). The issueKey must be valid and existent.
Example:  TST-234

 

warning
To perform the Get Commits API call, the Jira user must have the permission to read the requested issue.

 

Example:
http://jira.yourorg.com/rest/gitplugin/1.0/issues/TST-234/commits

Returns the following example result:

{
  "commits":[
    {
    "author": "msmith <mark@bigbrassband.com>",
    "commitId": "34efa20372f0e2f0c9b705aacc57d7ad82e01426",
    "date": "2015-05-18T10:52:54.000+0000",
    "message": "TST-234 Update link in documentation",
    "repository": {  INTRODUCED v2.11.0+
        "id": 5,
        "name": "test repository name"
      },
    "notes": {
        "refs/notes/commits": "TST-1 fixed also"
      },
    },
    {
    "author": "msmith <mark@bigbrassband.com>",
    "commitId": "52696c2d963be8986c7a2444b6473ea785632dce",
    "date": "2015-05-18T17:41:58.000+0000",
    "message": "TST-234 Remove libtiff dependency",
    }
  ]
}
showFiles Commits REST API
url
/rest/gitplugin/1.0/issues/{issueKey}/commits{?showFiles=[true|false]}

Extend the Commits API to review which files changed related to a specific Jira issue by adding ?showfiles=[true|false] as an optional parameter.
important
There are two types of users who can perform the Get Commit Issue Changes API call:
  1. Jira administrators
  2. Jira user who has all of the following:
    1. View/browse permissions to the project;
    2. View Development Tools permissions to the same project; and
    3. The repository is associated to the project.
method
GET
parameters
{issuekey} String. Required.
This is the Jira Issue Key - a concatenation of Project key and Issue number. It must contain a dash ("-"). The issueKey must be valid and existent.
Example:  TST-234
{?showFiles=[true|false]} Boolean. Optional.
When set to true, this extends the commits API to display which files where changed related to a specific Jira issue.
See usage example below.

 

warning
To perform the showFiles Commits API call, the Jira user must have the permission to read the requested issue.

 

Example:
Usage:
http://jira.yourorg.com/jira/rest/gitplugin/1.0/issues/TST-123/commits?showFiles=true

Returns the following example result, if showFiles=true:

{
  "commits": [
    {
      "author": "msmith <mark@bigbrassband.com>",
      "commitId": "257b4a8490270014922f3b821d61c86e76166dd9",
      "date": "2015-12-07 10:54:56 +0600",
      "message": "message with TST-123",
      "repository": {  INTRODUCED v2.11.0
        "id": 5,
        "name": "test repository name"
      },
      "notes": {
        "refs/notes/commits": "TST-1 fixed also"
      },
      "files": [
        {
          "path": "testFile2.txt",
          "linesAdded": 1,
          "linesChanged": 0,
          "linesDeleted": 0,
          "added": true,
          "deleted": false,
        }
      ]
    }
  ]
}
Get Commit Issue Changes REST API
description
Returns the list of issues associated with the commit.
important
There are two types of users who can perform the Get Commit Issue Changes API call:
  1. Jira administrators
  2. Jira user who has all of the following:
    1. View/browse permissions to the project;
    2. View Development Tools permissions to the same project; and
    3. The repository is associated to the project.
url
http://<jira-host>/rest/gitplugin/1.0/commit/{commitHash}/issues
method
GET
parameters
<jira-host> String. Required.
This is the default url location where you host your Jira.
Example:  http://local-host-jira.com:2990
{commitHash} String. Required.
This is the hash of the commit that you want the results from.
Example:  e012663bf9bd968388faa510cb5b310e4798c512
Example:
http://local-host-jira.com:2990/rest/gitplugin/1.0/commit/e012663bf9bd968388faa510cb5b310e4798c512/issues

 

Response:
{
 "success": true,
 "issueKeys":[
     "TST-999",
     "NEXT-3",
     "TST-6",
     "TST-2",
     "TST-1"
 ]
}
The resulting issueKeys are the existing Jira issues that are currently associated with the commit that has the specified commit hash.
Update Commit Issue Changes REST API
description
Updates the list of issues associated with the commit.
important
There are two types of users who can perform the Get Commit Issue Changes API call:
  1. Jira administrators
  2. Jira user who has all of the following:
    1. View/browse permissions to the project;
    2. View Development Tools permissions to the same project; and
    3. The repository is associated to the project.
url
http://<jira-host>/rest/gitplugin/1.0/repoId/{repoId}/commit/{commitHash}/issues
method
POST
parameters
<jira-host> String. Required.
This is the default url location where you host your Jira.
Example:  http://local-host-jira.com:2990
repoId,
{repoId}
Integer. Required.
Substitute repoId and {repoId} with the actual repository ID.
Tip: Use the Repository REST API to obtain the connected repositories' IDs.
Examples:
…/rest/gitplugin/1.0/1/2/…   –  Updates the commit association of the same commit in repos 1 and 2.
commitHash String. Required.
This is the hash of the commit on the Jira issue that you want to update changes to.
Example:  e012663bf9bd968388faa510cb5b310e4798c512
Example:
http://local-host-jira.com:2990/rest/gitplugin/1.0/1/2/commit/e012663bf9bd968388faa510cb5b310e4798c512/issues
In the case of the above example, the commit association(s) of the same commit for repo1 and repo2 will be updated using the parameters specified in the JSON request body.
The request body is a JSON structure supporting the following parameters:
Parameter Condition
a Adds a new issue key to associate to the commit.
d Disassociate the specified issue key from the commit.

 

Example request:
{
  "changeStrs": ["d:TST-5", "a:TST-6", "a:TST-7"]
}
The changeStrs modifier with the specified parameters will give the following result:
Removes association of TST-5; and
associates TST-6 and TST-7 to the same commit in repo1 and repo2.

« Hooks & API