March 28th 1 PM ET
Free Workshop: Escape the chaos of context-switching

Git Integration for Jira Self-Managed (Data Center/Server) Documentation

Add New Repository

Creates new repository from the given settings.

Only Jira admins can perform the Add New Repository API call.

 

url

/rest/gitplugin/1.0/repository

method

POST

Parameters

Request body is a JSON structure supporting the following parameters:

Field Description
displayName String. Optional.

This is the name that will appear in the Git Integration for Jira app repositories list.

origin String. 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.

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.

realRoot String. Required.

This is the local path to the repository on the server where your Jira service is running. It contains absolute path or relative path depending on absoluteRoot.

This field corresponds to the Repository root input box in the Advanced setup/Repository settings.

If this field is specified, absoluteRoot must also be defined.

absoluteRoot Boolean. Required.

This field shows whether realRoot is a relative path or absolute path.

If set to false, the realRoot is a path relative to ${JiraHOME}/data/git-plugin folder.

This field corresponds to the Cloned root location input field in the Advanced setup/Repository settings.

Repositories located in ${JiraHOME}/data/git-plugin folder are automatically managed by the Git Integration for Jira app.

If this field is specified, realRoot must also be defined.

disabled Boolean. Optional.

Set the repository status to updated (enabled) or disabled. If left blank, the default value for this field is false.

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.

sendCommitEmails Boolean. Optional.

Enables or disables commit notification emails for this repository.

maxMinsToCommitEmail Integer. 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.

hosted Internal field. Read-only.

This field will show whether the repository is hosted on Jira or not.

revisionIndexing Boolean. Optional.

This setting 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).

gitViewerEnabled Boolean. Optional.

Enables or disables the Repository Browser feature for this repository.  The default setting for this setting 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, Repository Browser.

username String. Critical for https origins.

Set as username for the git host. Leave blank if 2FA is enabled.

password String. Critical for https origins.

Set as password for the git host. Leave blank if 2FA is enabled.

pat String. Optional.

Personal access token. Required, if 2FA is enabled for the git host.

disableSslVerification Boolean. Optional. Default is false.

The SSL Verify setting is set to Enabled by default. If set to disabled, the Git Integration for Jira app 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.

smartCommitsEnabled Boolean. Optional.

This setting is enabled by default. Enables/disables smart commits processing for this repository or tracked folder. The default value for this field is true.

webLinkType String. Optional.

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. Optional.

This URL is unused and not being configured for the newly added integration types.

changesetFormat String. Optional.

This is the URL used to display revision.
Use the following variable: ${rev}  – git revision

fileAddedFormat,
fileModifiedFormat,
fileDeletedFormat
String. Optional.

This is the URL to display content of added, modified or deleted files.

Use the following variables:

  • ${num} – number of change (0, 1, …)
  • ${rev} – git revision
  • ${path}  –  path of the file being changed
  • ${parent}  –  parent git revision
  • ${blob}  –  ID of blob object
  • ${parent_blob}  –  ID of parent blob object
  • $convert(${branch},"subStr","newSubStr")  –  this inline function returns branch name with subStr replaced by a newSubStr. The ${branch} supports the character requirements on some hosting services.
mergeRequestFormat String. Optional.

This is the URL to display content of pull/merge requests on the git server.  Use the following variables:

* ${mergereqId} – ID of the pull/merge request

branchLinkFormat String. Optional.

This is the URL to display a branch on the git server. Use the following variables:

* ${branch} – Name of the branch

commitsValidationRequired Boolean. Optional.

This setting 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 Integration for Jira app.

If this setting 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.
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.

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.

Example: "projectMappingIds": [10000]

sourcesDiffViewEnabled Boolean. Optional.

When enabled, this setting allows Jira users with the View Development Tools and correct Jira/Git Integration for Jira app permissions to view the commit and file diffs inside Jira.

trustFolderStat Boolean. Optional.

When the trustFolderStat setting is set to false, the .git/objects/pack folder will be always scanned to check for new pack files. If set to true, the last-modified attribute of the folder will be used to check the folder for modifications.

The default value for Jira Data Center is false.

If your repository is stored on a network share, it is highly recommended to set this setting to false.

When adding new repositories, we recommend to leave this setting to false (default). You can change this setting later on via Actions ➜ Edit repository settings in the Manage repositories page.

refSpecNotes Boolean. Optional.
This is a reference to refs/notes/* used for fetching. The default value for this field is true.

Git notes are not shown…

  • when refs/notes are disabled on connecting a repository;
  • when a new note comes when refs/notes is disabled.
refSpecChanges Boolean. Optional.
This is a reference to refs/changes/* used for fetching. The default value for this field is false.
refSpecCustom String. Optional.
This is a user-defined list of references used for fetching. It is a comma-separated list with the format: +refs/refname1/*:refs/refname1/*, refs/refname2/*:refs/refname2/*, …
prHideFilter String. Optional.
Displays all pull requests for the specific issue, if left blank. Otherwise, set pull requests matching pattern to hide pull requests on issue pages that match the specified regular expression pattern.

 

Response

Adds a new repository to the Git Integration for Jira app repository configuration.

 

Example:

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

Request body (JSON) example:

{
  "displayName": "MyGitLab-testrepo",
  "origin": "https://github.com/johnsmith/test-repo.git",
  "mainBranch": "master",
  "absoluteRoot": false,
  "disabled": false,
  "enableFetches": true,
  "sendCommitEmails": true,
  "maxMinsToCommitEmail": 1440,
  "global": true,
  "hosted": false,
  "revisionIndexing": true,
  "gitViewerEnabled": true,
  "username": "",
  "password": "",
  "pat": "thisisthepatofyourgithost",
  "disableSslVerification": false,
  "smartCommitsEnabled": true,
  "webLinkType": "",
  "viewFormat": "",
  "changesetFormat": "",
  "fileAddedFormat": "",
  "fileModifiedFormat": "",
  "fileDeletedFormat": "",
  "commitsValidationRequired": true,
  "projectMappingIds": [
  ],
  "showAllTags": true,
  "sourcesDiffViewEnabled": true,
  "limitGitData": true,
  "refSpecNotes": true,
  "refSpecChanges": false,
  "trustFolderStat": true
}

Response:

Response:
{
  "id": 68,
  "displayName": "MyGitLab-testrepo",
  "origin": "https://github.com/johnsmith/test-repo.git",
  "mainBranch": "master",
  "root": "/opt/jira-home-shared/data/git-plugin/68_test-repo",
  "realRoot": "68_test-repo",
  "absoluteRoot": false,
  "disabled": false,
  "enableFetches": true,
  "sendCommitEmails": true,
  "maxMinsToCommitEmail": 1440,
  "global": true,
  "hosted": false,
  "initDate": 1626069618147,
  "revisionIndexing": true,
  "gitViewerEnabled": true,
  "disableSslVerification": false,
  "smartCommitsEnabled": true,
  "commitsValidationRequired": true,
  "requireUserPat": false,
  "projectMappingIds":[],
  "showAllTags": true,
  "supportsBranchCreationApi": false,
  "sourcesDiffViewEnabled": true,
  "refSpecNotes": true,
  "refSpecChanges": false,
  "trustFolderStat": false
}

 

Repository REST APIs

Retrieve Repository List

Add New Repository (this page)

Update Exisiting Repository

Delete Existing Repository

Have feedback about this article? Did we miss something? Let us know!
On this page