Hooks & APIs

Repository REST API

 

The Repository REST API allows query of the project repository list; as well as adding, updating and deleting repositories from the Git add-on repository configuration.

Retrieve Repository List
url
/rest/gitplugin/1.0/repository

Retrieves list of repositories mapped to a given project.
method
GET
parameters
projectKey          JIRA Project key (string).
Optional.  Query parameter.  If omitted, all imported repositories will be returned.

Example: Form param (projectKey: TST)
response
JSON

 

Example:
http://jira.yourorg.com/rest/gitplugin/1.0/repository?projectKey=TST


Response example:
{
  "success": true,
  "repositories": [
    {
      "id": 2,
      "displayName": "test-repo",
      "origin": "https://github.com/xxx",
      "root": "/xxx/xxx",
      "disabled": false,
      "enableFetches": true,
      "sendCommitEmails": true,
      "maxMinsToCommitEmail": 1440,
      "global": true,
      "hosted": false,
      "initDate": 1465462121864,
      "revisionIndexing": true,
      "revisionCacheSize": 10000,
      "gitViewerEnabled": true,
      "smartCommitsEnabled": true,
      "username": "",
      "password": "",
      "commitsValidationRequired": true
    },
    {
      "id": 1,
      "displayName": "gitrepo",
      "origin": "https://xxx@bitbucket.org/xxx",
      "root": "/xxx/xxx/xxx",
      "disabled": false,
      "enableFetches": true,
      "sendCommitEmails": true,
      "maxMinsToCommitEmail": 1440,
      "global": true,
      "hosted": false,
      "initDate": 1465462105842,
      "revisionIndexing": true,
      "revisionCacheSize": 10000,
      "gitViewerEnabled": true,
      "smartCommitsEnabled": true,
      "username": "",
      "password": "",
      "commitsValidationRequired": true
    }
  ]
}
 
Add New Repository
url
/rest/gitplugin/1.0/repository

Creates new repository from the given settings.
method
POST
parameters
Request body is a JSON structure supporting the following parameters:
Parameter Condition
displayName Required.
origin Required.
root Optional.
projectMappingIds Long [ ]. Array. Optional.
disabled Boolean. Optional.
enableFetches Boolean. Optional.
sendCommitEmails Boolean. Optional.
maxMinsToCommitEmail Optional.
global Boolean. Optional.
If set to true, the projectMappingIds parameter is ignored.  Otherwise the projectMappingIds parameter value(s) are applied.
hosted Boolean. Optional.
initDate Optional.
revisionIndexing Optional.
revisionCacheSize Optional.
gitViewerEnabled Boolean. Optional.
smartCommitsEnabled Boolean. Optional.
username Optional. Critical for https origins.
password Optional. Critical for https origins.
commitsValidationRequired Boolean. Optional.
For more information on each parameter, see Git Integration for JIRA add-on Documentation: Advanced setup open in new tab.
response
Adds a new repository to the Git add-on repository configuration.

 

Example:
http://jira.yourorg.com/rest/gitplugin/1.0/repository.json


Request body (JSON) example:
{
  "displayName": "myCustomRepo",
  "origin": "https://github.com/xxx/xxx.git",
  "projectMappingIds" : [10100],
  "disabled": false,
  "enableFetches": true,
  "sendCommitEmails": true,
  "maxMinsToCommitEmail": 1440,
  "global": false,
  "hosted": false,
  "initDate": 1465462121864,
  "revisionIndexing": true,
  "revisionCacheSize": 10000,
  "gitViewerEnabled": true,
  "smartCommitsEnabled": true,
  "username": "",
  "password": "",
  "commitsValidationRequired": false
}

Response:
{
  "id": 3,
  "displayName": "myCustomRepo",
  "origin": "https://github.com/xxx/xxx.git",
  "root": "/xxx/xxx/xxx/xxx/xxx",
  "disabled": false,
  "enableFetches": true,
  "sendCommitEmails": true,
  "maxMinsToCommitEmail": 1440,
  "global": false,
  "hosted": false,
  "initDate": 1465462121864,
  "revisionIndexing": true,
  "revisionCacheSize": 10000,
  "gitViewerEnabled": true,
  "smartCommitsEnabled": true,
  "username": "",
  "password": "",
  "commitsValidationRequired": false
}
 
Update Existing Repository
url
/rest/gitplugin/1.0/repository

Updates the existing repository from the given settings.
method
PUT
parameters
Request body is a JSON structure supporting the following parameters:
Parameter Condition
id ID of the existing repository. Required.
projectMappingIds Long [ ]. Array. Optional.
tagsFilter Optional.  Valid Java regular expression or an empty string.
displayName Optional.
origin Optional.
root Optional.
disabled Boolean. Optional.
enableFetches Boolean. Optional.
sendCommitEmails Boolean. Optional.
maxMinsToCommitEmail Optional.
global Boolean. Optional.
If set to true, the projectMappingIds parameter is ignored.  Otherwise the projectMappingIds parameter value(s) are applied.
hosted Boolean. Optional.
initDate Optional.
revisionIndexing Optional.
revisionCacheSize Optional.
gitViewerEnabled Boolean. Optional.
smartCommitsEnabled Boolean. Optional.
username Optional. Critical for https origins.
password Optional. Critical for https origins.
commitsValidationRequired Boolean. Optional.
For more information on each parameter, see Git Integration for JIRA add-on Documentation: Advanced setup open in new tab.
response
Updates the newly changed parameters to the selected repository.

 

Example:
http://jira.yourorg.com/rest/gitplugin/1.0/repository.json

Request body (JSON) example:
{
  "id": 3,
  "projectMappingIds": [],
  "tagsFilter": "release.*",
  "displayName": "renamedRepo",
  "origin": "https://github.com/xxx/xxx.git",
  "root": "/xxx/xxx/xxx/xxx/xxx",
  "disabled": true,
  "enableFetches": false,
  "sendCommitEmails": true,
  "maxMinsToCommitEmail": 2300,
  "global": true,
  "hosted": false,
  "initDate": 1465462121864,
  "revisionIndexing": true,
  "revisionCacheSize": 20000,
  "gitViewerEnabled": true,
  "smartCommitsEnabled": true,
  "username": "",
  "password": "",
  "commitsValidationRequired": false
}

Response:
{
  "id": 3,
  "displayName": "renamedRepo",
  "origin": "https://github.com/xxx/xxx.git",
  "root": "/xxx/xxx/xxx/xxx/xxx",
  "disabled": true,
  "enableFetches": false,
  "sendCommitEmails": true,
  "maxMinsToCommitEmail": 2300,
  "global": true,
  "hosted": false,
  "initDate": 1465462121864,
  "revisionIndexing": true,
  "revisionCacheSize": 20000,
  "gitViewerEnabled": true,
  "smartCommitsEnabled": true,
  "username": "",
  "password": "",
  "commitsValidationRequired": false
}
 
Delete Existing Repository
url
/rest/gitplugin/1.0/repository

Deletes the existing repository from the Git add-on repository configuration.
method
DELETE
parameters
Request body is a JSON structure supporting the following parameters:
Parameter Condition
id ID of the existing repository. Required.
deleteFiles Boolean. Optional.
Indicates whether the repository folder is also deleted from the JIRA server.  If set to false, the repository folder is deleted from the JIRA server.
For more information on each parameter, see Git Integration for JIRA add-on Documentation: Advanced setup open in new tab.
response
Deletes the repository from the Git add-on repository configuration.  Also, the repository folder is also deleted from the JIRA server if the deleteFiles parameter is set to true.

 

Examples:
Example 1:
http://jira.yourorg.com/rest/gitplugin/1.0/repository?id=3&deleteFiles=true

Response:
{
  "success": true
}


Example 2:
http://jira.yourorg.com/rest/gitplugin/1.0/repository?id=5

Response:
{
  "success": false,
  "error": "Repository with id=5 does not exist",
  "advice": "Please try again with an existing repository id."
}