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

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

Editing existing repository settings in the TSV File

Navigate to the .tsv file and edit it with your favorite spreadsheet program.

Google Drive is also a recommended place to edit the .tsv file.

 

Populate/edit the fields by utilizing the following options:

id

Integer. Required.

Assign an ID number to a repository.

This field is required if you wish to update or edit existing repositories by setting this value to their equivalent IDs. Otherwise, if this field is left blank, the repository will be created as new.

Important!
When importing to a new server, the id field must be blank.

realRoot

StringOptional on existing servers.

This is the local path to the repository on the server where your Jira service is running. This will point the Git Integration for Jira app to a clone of the repository hosted locally with Jira.

The realRoot field may refer to an existing repository on a new server. If root doesn’t exist, this field must be blank.

absoluteRoot

Boolean. Optional.

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

If this field is set to true, the repository is automatically managed by Git Integration for Jira app (stored in $JiraHOME). If set to false, the repository is manually configured by the Jira administrator.

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

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.

SSH INTEGRATION

Before adding repositories (new or existing) via Bulk change, make sure that you have added SSH keys for the respective git hosts in the Git Integration for Jira app configuration page. BigBrassBand recommends to use the git@<url>:[your-git-repo].git format for the repository origin URL and adding of SSH Keys for each git host in the Git Integration for Jira app configuration page.

HTTPS/HTTP INTEGRATION

For HTTPS git repositories, obtain the URL from your git host. If you use HTTP/HTTPS URLs in the origin field, the Git Integration for Jira app will not be able to import said repositories due to missing credentials. Entering repository login credentials in the TSV file is not advisable due to a possible security risk. Therefore, when editing the origin field of the TSV file, enter value using the git@<repository-url>:[your-git-repo].git format. This format will use the SSH key(s) from the Git Integration for Jira app configuration instead.

The repository origin may not be hosted on the same server as Jira.

displayName

String. Optional.

Define a meaningful name for this repository configuration. This is the name that will appear in the Git Integration for Jira app repositories list. If this field is left blank, the default value is obtained from the origin.

enableFetches

Boolean. Optional.

Set to true to enable fetches on git repositories hosted on remote servers. In this mode, fetches are enabled using any external source. The reindex background service will initiate the fetch then add the new commits to the plugin index.

Set to false to enable fetches on git repositories hosted on the same server as Jira. Fetches are enabled when the repository is hosted locally. In this mode, no fetches are made. The reindex service runs in the background and process every new commit found.

revisionIndexing

Boolean. Optional.

The default value for this field is true.

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

mainBranch

String. Optional.

Set specific branch as the main branch for this repository. 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.

Default Main Branch
Most git integrations allow changing of the default branch of the repository/project other than master at the server level. On each reindex, this change is reflected in the Repository Settings. In the case of Gerrit, the default main branch is always master.

username, password

String. Optional.

Critical for https origins. Define username and password for the git host. Leave blank if 2FA is enabled in your git host.

pat

String. Optional.

Required, if 2FA is enabled for the git host. This field accepts personal access token from supported git hosts.

gitViewerEnabled

Boolean. Optional.

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

projectMapping

Long [ ]. Array. Optional.

These are numeric projects IDs associated with the repository.

  • This field accepts list of comma separated project IDs for project mapping. Trailing spaces are ignored (equivalent to unchecking the Associate to All Projects checkbox).

    Example: 10000,10100

  • If you change an existing repository, leaving this field blank will use the existing values of the repository configuration.

  • Setting this field to ALL will retain projectMapping settings and sets the “All Projects” flag to true (equivalent to checking the Associate to All Projects checkbox).

  • If projects are not associated to the repository, you must leave this field blank and set the gitViewerEnabled field to false.

smartCommitsEnabled

Boolean. Optional.

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

sendCommitEmails

Boolean. Optional.

Enables or disables commit notification emails for this repository. If left blank, the default value for this field is true.

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.

changesetFormat, 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
  • `${sha256path}` – sha256 applied to the path and hex encoded. NEW! in v4.17+ and is used in GitHub.com weblinking.
  • `${md5}` – md5 applied to the path and hex encoded. NEW! in v4.17+ and is used in GitHub EE weblinking.
  • `${sha1path}` – sha1 applied to the path and hex encoded. NEW! in v4.17+ and is used in GitLab weblinking.
  • `${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} code has been changed to cope up with the character requirements on some hosting services.

disabled

Boolean. Optional.

Add this repository into the Git Integration app configuration and set its 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.

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.

Set tagsFilter with a valid Java regular expression or an empty string. The filtered tags are displayed on the Jira Developer Panel.

For more information, see example in Git tags.

requireUserPat

Boolean. Optional.

Setting this field to true will require users to specify their own PAT for branch and pull/merge request management. If left blank, the default value of this field is false.

integrationType

Boolean. Internal field.

This field will show whether the repository is a tracked folder, a connected GitLab server or a simple repository.

trackedFolderId

Integer. Internal field.

This field will display the ID of the “parent” repository. It can be changed in order to convert the repository to a sub-repository.

Use with caution
If the modified sub-repository is not located in the tracked folder, it will be removed by the sequential auto-reindex.

delete

Flag. Optional.

Set “delete” on this column/field as a confirmation to the Git Integration app to automatically remove the selected repository from the plugin configuration. If left blank, no changes will occur.

sshKeyId

Integer. Optional.

This is the ID of an associated SSH key.

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.

apiPath

String. Optional.

The integration will use this relative REST API path starting with “/” to retrieve the list of tracked repositories.

For more information, see Working with Custom API Path.

apiFilter

String. Optional.

JMESPath filter expression will be used to filter API results.

See our Integration GuidesWorking with JMESPath filters or contact support for help writing expressions.

tfsCollection

String. Optional. TFS or Azure DevOps Server integrations only.

A TFS collection is a group of TFS team projects. Specify an existing TFS Collection for use with Jira integration.

awsRegion

String. Optional. AWS integrations only.

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

Git Integration for Jira app supported regions:

Region codes
us-east-1 us-east-2 us-west-1 us-west-2
ap-south-1 ap-northeast-2 ap-southeast-1 ap-southeast-2
ap-northeast-1 ca-central-1 eu-central-1 eu-west-1
eu-west-2 eu-west-3 eu-north-1 me-south-1
sa-east-1

sslVerify

Boolean. Optional.

Default is TRUE. The SSL Verify option is set to enabled by default. If set to FALSE, 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 menu Git ➜ Manage repositories ➜  Actions ➜ Edit repository/integration settings.

trustFolderStat

When this field 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 Server is true.

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 field to false.

weblinkType

String. Optional.

Set web link type equivalent to the connected git host. Set web linking formats by referring to Documentation – Web linking.

viewFormat

String. Optional.

This is the URL to display diff from some git hosts. Other git hosts does not use this field.

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

refSpecNotes

Boolean. Optional.

This is a reference to refs/notes/* used for fetching. The default value for this field is false.

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.

 


Take note that the .tsv file is verified by the Git for Jira app with the following rules:

  • The header row is required.
  • The order of fields specified in the header row – is the order of the fields in the following rows.
  • If a field is omitted from the header row, the Git Integration app will use the default value for a new repository. The Git Integration app will keep the current value of a repository if it already exists in the configured repositories.
  • If a repository is not listed in the .tsv file, no changes will be made if the same repository exists in the add-on configuration.

Save the file to a tab-delimited format:

  • OSX users – select all data in Numbers and then paste into a text editor and save. Name the file with the .tsv extension (repo-example-00.tsv).

  • Excel users – save the file as Text (Tab delimited) (*.txt). Rename file’s .txt extension to .tsv.

  • Google Drive – upload the file to this service. Right click the .tsv file then open it with Google Sheets.  Make the necessary changes then go to File ➜ Download as ➜ Tab separated values (.tsv) to your local machine.

 


 

Prev: Import new repositories via Bulk change

Next: Removing existing repositories via Bulk change

 

More related articles on Bulk change

Exporting repository configuration via Bulk change

Requirement for secured import

Import existing repositories via Bulk change

Import new repositories via Bulk change

Editing existing repository settings in the TSV File (this page)

Removing existing repositories via Bulk change

Bulk change (index)

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