Documentation

Bulk Change

The Bulk Change feature provides an easier way to import or export repository configuration.

Exporting Repository Configuration via Bulk Change

The bulk export function allows Jira administrators to create a backup copy of the Git Integration for Jira app repository configuration into a tab-delimited (TSV) file.

1. On your Jira dashboard, go to menu Git ➜ Manage repositories. (Alternatively, go to Jira Administration ➜ Applications. Under Git Integration for Jira, select Git repositories.)
2. Click Bulk Change then select Export configuration.

3. Click Download to save the current configuration of your repositories to a specified location.

For detailed instructions on importing multiple repositories in the Git Integration for Jira app configuration, click on the Detailed instructions label or follow the steps in the next section.

Requirement for Secured Import

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 for Jira app SSH Keys configuration page. For example, you have GitHub and GitLab repositories to import, add the private SSH keys to the Git for Jira app SSH Keys for each git host.

If you use HTTP/HTTPS URLs in the origin field, the Git 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 in git@<repository-url>:[your-git-repo].git format since it will use the SSH key(s) from the Git for Jira app configuration instead.

Adding Existing Repositories via Bulk Change

For administrators who have several repositories, the Git Integration for Jira app allows you to import multiple repository configuration using a .tsv file. This will make managing large Git repository lists more efficient.

1. Click Choose File... on the Import repository configuration screen.
2. Navigate to the location of the .tsv file then click Open.
3. Click Upload to start the import process.

The Git for Jira app will read the list from the file, detect the existing configured repositories, and automatically update its settings. If an error is found, it will be displayed in the message log on the import screen and in the Status column on the repository configuration list. Make the required changes to correct the errors on the affected rows and redo the upload.

Adding New Repositories via Bulk Change

Download the template file or follow the above section if you already have the .tsv file ready for import:

1. On your Jira dashboard, go to menu Git ➜ Manage repositories. (Alternatively, go to Jira Administration ➜ Applications. Under Git Integration for Jira, select Git repositories.)
2. Click Bulk Change then select Import configuration.

The following screen is displayed:

Click one of the links under How to use Bulk change? to download the template file.

Editing Existing Repositories 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:

  Column/Field	Description
  id	Integer. *Required/Optional. Assign an ID number to a repository. * This is required if you wish to update or edit existing repositories by setting this value to their equivalent IDs. If this field is left blank, the repository will be created as new. When importing to a new server, the "id" field must be blank.
  realRoot	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. This field corresponds to the Repository root input box in the Advanced setup/Repository settings. The "realRoot" field may refer to an existing repository on a new server. If "root" doesn't exist, this field must be blank. If this field is specified, absoluteRoot must also be defined.
  absoluteRoot	Boolean. Optional. This field corresponds to the Cloned root location input field in the Advanced setup/Repository settings. If 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. 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 for Jira app configuration page. For HTTPS git repositories, obtain the URL from your git host then set your login credentials in the username and password (or pat) field to connect to them.
  displayName	String. Required. Define a meaningful name for this repository configuration. 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. Set to false to enable fetches on git repositories hosted on the same server as Jira. See Enable Fetches section in Adding a Repository via Advanced Setup. The default boolean value for this field is true.
  revisionIndexing	Boolean. Optional. The default boolean 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).
  revisionCacheSize	Integer. 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 for this field is 10000. Higher values can affect the performance of the retrieved revisions from Git.
  mainBranch	String. Optional. Set specific branch as the main branch for this repository. The default value is "master". See Main Branch section in Adding a Repository via Advanced Setup.
  username,password	String. Optional. See Use basic http authentication section in Adding a Repository via Advanced Setup. Leave blank if 2FA is enabled for the 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 value for this option is enabled. For more information, see section, Repository Browser. Users must have the View Development Tools project permission in order to use this feature. Consult your Jira System Administrator on permissions.
  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 in the Advanced Setup dialog) 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 "All Projects" flag to true (equivalent to checking the Associate to All Projects checkbox in the Advanced Setup dialog). If projects are not associated to the repository, you must leave this field blank and set the gitViewerEnable field to false.
  smartCommitsEnabled	Boolean. Optional. This setting is enabled by default (as of v2.6.3+ of the Git Integration app). Enables/disables smart commits processing for this repository or tracked folder. The default value for this field is?true.
  sendCommitEmails	Boolean. Optional. Send 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. Default value is 1440 minutes.
  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. As of v2.11.0+ of the Git Integration app, the ${branch}?code has been changed to cope up with 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
  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. Internal field. Read-only. This field will show whether the repository is hosted on Jira or not.
  tagsFilter	String. Optional. 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 on this topic, see Git Tags.
  integrationType	Flag. Internal field. This field will show whether the repository is a tracked folder, a connected GitLab server or a simple repository.
  trackedFolderId	Flag. 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 for Jira 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.
  limitGitData	The Limit commits feature is deprecated after January 1, 2021. From then on, all commits will be limited by project permissions. Boolean. Optional. Enables/disables limitation of commits shown in Git Commits issue tab, Git Commits page and all across the Git Integration for Jira app by project association. This only applies when project associations are set (projectMapping). When limitGitData is set to true for a git repository and there are project associations set (projectMapping) — The git data is not shown from that repository in any project except those from projectMapping. Unless the issue is from a project association list in projectMapping, 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. limitGitData defaults to true when setting new project associations. limitGitData Upgrade and installation defaults: Condition Repository Result Upgrade to new app version Has several repositories with project associations Defaults to false because there is no sudden change in behavior Upgrade to new app version Adds a new repository and set project associations Defaults to true because it is a new repository Installs app for the first time Adds a new repository and set project associations Defaults to true because it is a new repository
  requireUserPat	Boolean. Optional. Require users to specify their own PAT for branch and pull/merge request management.
  sourcesDiffViewEnabled	Boolean. Optional. Jira users that have the "View Development Tools" permissions and correct Jira/Git Integration app project permissions can view the diff by commit and file.
  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 Manage git repositories > Actions > Edit integration/repository settings.
  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 Custom API Path master page at Confluence.
  apiFilter	String. Optional. JMESPath filter expression will be used to filter API results. See our Integration Guide at Confluence, JMESPath Filter master page at Confluence or contact support for help writing expressions.
  tfsCollection	String. Optional. TFS integrations only. A TFS collection is a group of TFS team projects. Specify an existing TFS Collection for use with Jira integration.
  awsRegion	Boolean. Optional. AWS integrations only. Specify a region for AWS CodeCommit integration. Supported regions: 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-northwest-2 ca-central-1 eu-central-1 eu-west-1 eu-west-2 eu-west-3 eu-north-1 me-south-1 sa-east-1
  trustFolderStat	Boolean. Optional. When this 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 instead to check the folder for modifications. The default value for Jira Server is True. For Jira Data Center, it's False. If your repository is stored on a network share, it is highly recommended to set this value to false. Jira Data Center. When adding new repositories, we recommend to leave this setting to false (default for Data Center). 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/*, ...

  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 add-on will use the default value for a new repository. The Git add-on 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.

Removing Existing Repositories via Bulk Change

To delete multiple repositories from Git Integration for Jira app repository configuration:

1. Open the existing .tsv file that you want to use for this process. See the previous section for more information.
2. Under the delete column, enter "delete" for each repository that you want to remove.
3. Save this file and upload it via Bulk change ➜ Import configuration.

Bulk Change Automation

To automate the bulk change process via script, see Bulk Change API.