Hooks & APIs

Repository REST API

 

Last Updated: February 6, 2018

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",
      "mainBranch": "master",
      "disabled": false,
      "enableFetches": true,
      "sendCommitEmails": true,
      "maxMinsToCommitEmail": 1440,
      "global": true,
      "hosted": false,
      "initDate": 1465462121864,
      "revisionIndexing": true,
      "revisionCacheSize": 10000,
      "gitViewerEnabled": true,
      "disableSslVerification": false,
      "smartCommitsEnabled": true,
      "commitsValidationRequired": true,
      "tagsFilter": "",
      "showAllTags": true,
      "supportsExternalApi": false,
      "sourcesDiffViewEnabled": true,
      "limitGitData": true
    },
    {
      "id": 1,
      "displayName": "gitrepo",
      "origin": "https://xxx@xxx.gitlab.org/xxx",
      "root": "/xxx/xxx/xxx",
      "mainBranch": "master",
      "disabled": false,
      "enableFetches": true,
      "sendCommitEmails": true,
      "maxMinsToCommitEmail": 1440,
      "global": true,
      "hosted": false,
      "initDate": 1465462105842,
      "revisionIndexing": true,
      "revisionCacheSize": 10000,
      "gitViewerEnabled": true,
      "disableSslVerification": false,
      "smartCommitsEnabled": true,
      "webLinkType": "gitlab",
      "viewFormat": "",
      "changesetFormat": "http://xxx.gitlab.com/xxx/xxx/commit/${rev}",
      "fileAddedFormat": "http://xxx.gitlab.com/xxx/xxx/commit/${rev}",
      "fileModifiedFormat": "http://xxx.gitlab.com/xxx/xxx/commit/${rev}",
      "fileDeletedFormat": "http://xxx.gitlab.com/xxx/xxx/commit/${rev}",
      "commitsValidationRequired": true,
      "tagsFilter": "",
      "showAllTags": true,
      "supportsExternalApi": false,
      "sourcesDiffViewEnabled": true,
      "limitGitData": 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.
This is the name that will appear in the Git add-on repositories list.
origin Required.
This is the URL to the hosted git service used on the project.
For example, you might host your repository on GitHub, Beanstalk or your own server.
root Optional.
This is the local path to the repository on the server where your Jira service is running.  This will point the Git add-on to a clone of the repository hosted locally with Jira.
enableFetches Boolean. Optional.
Set to true to enable fetches on git repositories hosted on remote servers.
Set to false to enable fetches on git repositories hosted on the same server as Jira.
mainBranch String. Optional.
The specified branch will intend to organize the Git Commit tab.  A commit will not be shown in other branches if it is a part of the main branch.  By default, "master" will be used if a main branch is not specified.
revisionIndexing Optional.
This option turns on the memory cache which is used when list of commits are displayed.  Set to true if revision indexing will index and link to any mentioned issue keys in the revision history or not (false).
revisionCacheSize Optional.
This is the size of the memory cache.  If some particular commit is not cached, it is fetched from the Lucene index which involves some disk activity.
Enter the number of revisions to keep the cache in memory.  The default value is 10000.
fyi
Higher values can affect the performance of the retrieved revisions from Git.
username Optional. Critical for https origins. Set as username for the git host.
password Optional. Critical for https origins. Set as password for the git host.
pat String. Personal access token. Required, if 2FA is enabled in the git host.
disableSslVerification Boolean. Optional. Default is false.
The SSL Verify option is set to Enabled by default.  If set to disabled, the Git Integration for Jira add-on will ignore verification of SSL certificates when connecting to a git server.
This setting can also be accessed via Manage git repositories > Actions > Edit repository settings.
sendCommitEmails Boolean. Optional.
Enables or disables commit notification emails for this repository.
maxMinsToCommitEmail Optional.
Set the desired value in minutes, as to when commit notifications will be sent.  Commit notifications will be e-mailed if the age of the commit is less than or equal to this value.
global Boolean. Optional.
If set to true, the projectMappingIds parameter is ignored.  Otherwise the projectMappingIds parameter value(s) are applied.
projectMappingIds Long [ ]. Array. Optional.
These are numeric projects IDs associated with the repository.  When you create a new repository and set the field gitViewerEnabled  to true, at least one project must be associated with it.
disabled Boolean. Optional.
Set the repository status to updated (enabled) or disabled.  If left blank, the default value for this field is false.
hosted Boolean. Optional.
Internal field. Read-only. This field will show whether the repository is hosted on Jira or not.
gitViewerEnabled Boolean. Optional.
Enables or disables the Repository Browser feature for this repository.  The default setting for this option is enabled.  Users must have the View Development Tools project permission in order to use this feature.  Consult your Jira System Administrator on permissions.  For more information, see section, The Repository Browser.
smartCommitsEnabled Boolean. Optional.
This setting is enabled by default (as of v2.6.3 of the Git add-on).  Enables/disables smart commits processing for this repository or tracked folder.  The default value for this field is true.
tagsFilter String. Optional. Displays all tags for the specific issue, if left blank.  Otherwise, set tags matching pattern to display tags on issue pages that match the specified regular expression pattern.
For more information, see example in Show tags.
commitsValidationRequired Boolean. Optional.
This option is only applicable to self-hosted git servers.  For example, you are hosting your git repositories in your own server such as GitLab CE/EE or GitHub Enterprise.  If a developer tries to push a commit without the issue key in its message, the push is rejected by the Git add-on.
If this option is enabled, the commit messages are validated according to the following rules:
  • The commit message contains at least one issue key.
  • The issue key is valid.
  • The issue key exists.
sourcesDiffViewEnabled Boolean. Optional.
When enabled, this setting allows Jira users with the View Development Tools and correct Jira/Git Integration for Jira add-on permissions to view the commit and file diffs inside Jira.
webLinkType String.  Set web link type equivalent to the connected git host.  Set web linking formats by referring to Git Integration for Jira: Web Linking.
viewFormat String.
changesetFormat String.
fileAddedFormat String.
fileModifiedFormat String.
fileDeletedFormat String.
limitGitData Boolean. Optional.
Enables/disables limitation of commits shown in Git Commits issue tab, Git Commits page and all across the Git Integration for Jira add-on by project association.  This only applies when project associations are set (projectMappingIds).
When limitGitData is set to true for a git repository and there are project associations set (projectMappingIds) — The git data is not shown from that repository in any project except those from projectMappingIds.
Unless the issue is from a project association list in projectMappingIds, some data are not shown such as:
  • Commits, branches and tags in the Issue sidebar.
  • Commits in Git Commits tab.
  • Commits in Git Commits page.
  • Commits and branches in Git Roll Up tab.
  • Commits in Project/Issue pages.
  • Commits in Compare pages. User read/view permission restriction also applies.
fyi
limitGitData defaults to true when setting new project associations.
limitGitData Upgrade and installation defaults:
Condition Repository Result
Upgrade to new add-on version Has several repositories with project associations Defaults to false because there is no sudden change in behavior
Upgrade to new add-on version Adds a new repository and set project associations Defaults to true because it is a new repository
Installs add-on for the first time Adds a new repository and set project associations Defaults to true because it is a new repository
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",
  "enableFetches": true,
  "revisionIndexing": true,
  "revisionCacheSize": 10000,
  "mainBranch": "master",
  "username": "",
  "password": "",
  "pat": "",
  "disableSslVerification": false,
  "gitViewerEnabled": true,
  "global": false,
  "projectMappingIds" : [10100],
  "sendCommitEmails": true,
  "maxMinsToCommitEmail": 1440,
  "webLinkType": "",
  "viewFormat": "",
  "changesetFormat": "",
  "fileAddedFormat": "",
  "fileModifiedFormat": "",
  "fileDeletedFormat": "",
  "disabled": false,
  "hosted": false,
  "tagsFilter": "",
  "smartCommitsEnabled": true,
  "sourcesDiffViewEnabled": true,
  "commitsValidationRequired": false,
  "limitGitData": false
}

Response:
{
  "id": 3,
  "displayName": "myCustomRepo",
  "origin": "https://github.com/xxx/xxx.git",
  "root": "/xxx/xxx/xxx/xxx/xxx",
  "enableFetches": true,
  "revisionIndexing": true,
  "revisionCacheSize": 10000,
  "mainBranch": "master",
  "disableSslVerification": "false",
  "gitViewerEnabled": true,
  "projectMapping" : [10100],
  "sendCommitEmails": true,
  "maxMinsToCommitEmail": 1440,
  "webLinkType": "",
  "viewFormat": "",
  "changesetFormat": "",
  "fileAddedFormat": "",
  "fileModifiedFormat": "",
  "fileDeletedFormat": "",
  "disabled": false,
  "global": false,
  "hosted": false,
  "initDate": 1465462121864,
  "tagsFilter": "",
  "smartCommitsEnabled": true,
  "sourcesDiffViewEnabled": true,
  "commitsValidationRequired": false,
  "limitGitData": false
}
 
Update Existing Repository
url
/rest/gitplugin/1.0/repository

Updates the existing repository from the given settings.
method
PUT
parameters
The Request body is a JSON structure similar to the Add New Repository API plus the id parameter:
Parameter Condition
id Integer. Required.
This is the ID of the existing repository. For example, id : 3,.
The Update Repository API will look for the repository with id : 3 and replaces repository properties according to the declared JSON request body structure file.
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,
  "displayName": "renamedRepo",
  "origin": "https://github.com/xxx/xxx.git",
  "root": "/xxx/xxx/xxx/xxx/xxx",
  "enableFetches": true,
  "revisionIndexing": true,
  "revisionCacheSize": 10000,
  "mainBranch": "master",
  "disableSslVerification": "false",
  "gitViewerEnabled": true,
  "projectMappingIds" : [],
  "sendCommitEmails": true,
  "maxMinsToCommitEmail": 1440,
  "webLinkType": "",
  "viewFormat": "",
  "changesetFormat": "",
  "fileAddedFormat": "",
  "fileModifiedFormat": "",
  "fileDeletedFormat": "",
  "disabled": true,
  "global": false,
  "hosted": false,
  "initDate": 1465462121864,
  "tagsFilter": "",
  "smartCommitsEnabled": true,
  "sourcesDiffViewEnabled": true,
  "commitsValidationRequired": false,
  "limitGitData": false
}

Response:
{
  "id": 3,
  "displayName": "renamedRepo",
  "origin": "https://github.com/xxx/xxx.git",
  "root": "/xxx/xxx/xxx/xxx/xxx",
  "enableFetches": true,
  "revisionIndexing": true,
  "revisionCacheSize": 10000,
  "mainBranch": "master",
  "disableSslVerification": "false",
  "gitViewerEnabled": true,
  "projectMapping" : [],
  "sendCommitEmails": true,
  "maxMinsToCommitEmail": 1440,
  "webLinkType": "",
  "viewFormat": "",
  "changesetFormat": "",
  "fileAddedFormat": "",
  "fileModifiedFormat": "",
  "fileDeletedFormat": "",
  "disabled": true,
  "global": false,
  "hosted": false,
  "initDate": 1465462121864,
  "tagsFilter": "",
  "smartCommitsEnabled": true,
  "sourcesDiffViewEnabled": true,
  "commitsValidationRequired": false,
  "limitGitData": 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."
}