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

Contact Support
GitKraken Status  

Update Existing Integration API

Updates the existing parameters of the specified integration.

Only Jira admins can perform the Update Integration API call.

url

{JiraBaseURL}/rest/gitplugin/1.0/integration/{integrationId}

integrationId

Integer. Required.

This is the ID of the existing integration. For example, /integration/3.

Using the integrationId from the url, the Update Integration API will look for the integration with id : 3 and replaces integration properties according to the declared JSON request body structure file.

method

PUT

content-type

application/json

parameters

The Request body is a JSON structure similar to the Add New Integration API. Unlike the Update Existing Repository API, the id of the integration is substituted to the url as integrationId.

Field Description
displayName String. Optional. Some git hosts may require this to be filled in.

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

origin String. Optional.

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.

Example URL: https://api.github.com

disabled Boolean. Optional.

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

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.

type String. Optional.

The type of integration. Available values are the following:

  • GITHUB – integration with Github.com
  • GITHUB_SERVER – integration with GitHub Enterprise
  • GITLAB – integration with GitLab.com
  • GITLAB_SERVER – integration with GitLab Server (CE/EE) (APIv4)
  • GITLAB_SERVER_LEGACY – integration with GitLab Server (CE/EE) Legacy (APIv3)
  • FILESPACE – integration for a tracked folder
  • AZURE_DEVOPS – integration with Azure DevOps Repos
  • VSTS – integration with Visual Studio Team Services (VSTS)
  • AZURE – integration with Azure DevOps Server
  • TFS_SERVER – integration with Team Foundation Server (TFS)
  • AWS – integration with AWS CodeCommit
  • GERRIT – integration with Gerrit Code Review
username String. Optional.

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

password String. Optional.

Set as password for the git host. Leave blank if 2FA is enabled. Otherwise, fill this in if password has changed.

pat String. Optional.

This field accepts personal access token from supported git hosts. Fill this in if 2FA is enabled for the git host and if the PAT has changed.

disableSslVerification Boolean. Optional.

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 repositories ➜ Actions ➜  Edit integration.
apiPath String. Optional.

The integration will use the relative REST API path starting with “/” to retrieve the list of tracked repositories. For more information, see article Working with Custom API path.

apiFilter String. Optional.

It is a JMESPath filter expression. The expression will be used to filter API results such as repository names, etc. For more information, see article Working with JMESPath filters.

tfsCollection String. Optional.

Specify the specific collection to connect. It is used for Microsoft integrations only.

awsRegion String. Optional.

Specify AWS region; where CodeCommit repositories are located. The list of regions with their names can be found here.

Supported regions:

  • us-east-1
  • us-east-2
  • us-west-1
  • us-west-2
  • af-south-1
  • ap-east-1
  • ap-outh-1
  • ap-south-2
  • ap-northeast-3
  • ap-northeast-2
  • ap-southeast-1
  • ap-southeast-3
  • ap-southeast-2
  • ap-northeast-1
  • ca-central-1
  • eu-central-1
  • eu-central-2
  • eu-west-1
  • eu-west-2
  • eu-west-3
  • eu-south-1
  • eu-south-2
  • eu-north-1
  • me-central-1
  • me-south-1
  • sa-east-1
requireUserPat Boolean. Optional.

Setting this parameter to true will require users to specify their own PAT for branch and pull/merge request management.

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.

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.

global Boolean. Optional.

If set to true, the projectMappingIds parameter is ignored. Otherwise the projectMappingIds parameter value(s) are applied.

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.

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

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.

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.

The trustFolderStat setting can be configured for each repository in the integration.
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/*, …

folderDepth Integer. Optional.
Valid value range: 1 – 5
This parameter is required if integrationType = FILESPACE.
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

Updates the recent changes of the parameters for the specified integration.

Example 1:
http://jira.yourorg.com/rest/gitplugin/1.0/integration/1

Request body (JSON) example:

{
  "displayName": "MY GITLAB",
  "origin": "https://gitlab.com",
  "disabled": false,
  "sendCommitEmails": true,
  "maxMinsToCommitEmail": 1440,
  "global": true,
  "pat": "thisisthepatofyourgithost",
  "revisionIndexing": true,
  "gitViewerEnabled": true,
  "disableSslVerification": false,
  "smartCommitsEnabled": true,
  "requireUserPat": false,
  "projectMappingIds": [],
  "integrationType": "GITLAB",
  "sourcesDiffViewEnabled": true,
  "refSpecNotes": true,
  "refSpecChanges": false,
  "trustFolderStat": false,
}

Response:

{
    "success": "true",
    "integration": {
        "id": 1,
        "displayName": "MY GITLAB",
        "origin": "https://gitlab.com",
        "disabled": false,
        "sendCommitEmails": true,
        "maxMinsToCommitEmail": 1440,
        "global": true,
        "initDate": 1574747787950,
        "lastIndexedDate": 1584720012000,
        "revisionIndexing": true,
        "gitViewerEnabled": true,
        "disableSslVerification": false,
        "smartCommitsEnabled": true,
        "projectMappingIds": [],
        "integrationType": "GITLAB",
        "sourcesDiffViewEnabled": true,
        "refSpecNotes": true,
        "refSpecChanges": false,
        "trustFolderStat": false
    }
}

 

Example 2: Restrict an integration to project(s)
http://jira.yourorg.com/rest/gitplugin/1.0/integration/1

Request body (JSON) example:

{
  "id": 1,
  "pat": "thisisthepatofyourgithost",  
  "gitViewerEnabled": true,  
  "smartCommitsEnabled": true,
  "global": false,
  "projectMappingIds": [ 10000 ],  
}

// The endpoint does not accept the "projectMappingIds" list when "global" is set to 'true'.

Response:

{
    "success": "true",
    "integration": {
        "id": 1,
        "displayName": "MY GITLAB",
        "origin": "https://gitlab.com",
        "disabled": false,
        "sendCommitEmails": true,
        "maxMinsToCommitEmail": 1440,
        "global": false,
        "initDate": 1574747787950,
        "lastIndexedDate": 1584720012000,
        "revisionIndexing": true,
        "gitViewerEnabled": true,
        "disableSslVerification": false,
        "smartCommitsEnabled": true,
        "projectMappingIds": [ 10000 ],
        "integrationType": "GITLAB",
        "sourcesDiffViewEnabled": true,
        "refSpecNotes": true,
        "refSpecChanges": false,
        "trustFolderStat": false
    }
}

 

Integration REST APIs

Add New Integration

Add New Integration Type API (examples)

Update Existing Integration (this page)

Remove Integration

Retrieve an Integration

Retrieve Integration List

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