Bulk Change Jira Server

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

warning
To perform the following steps in this section, Git Add-on for Jira v2.4 or later is required.  Please upgrade if you have a lower version of the add-on.

Exporting Repository Configuration via Bulk Change

The bulk export function allows Jira administrators to create a backup copy of the Git ad-on repository configuration into a tab-delimited file.

  1. Go to cog Administration > Add-ons.  Under Git Integration Plugin for Jira, select Git Repositories.
  2. helpful tip
    If using Jira 7, go to Administration  > Add-ons. Select Applications on the page tab. Under Git Integration Plugin for Jira on the sidebar, select Git Repositories.
  3. Click  Bulk Change dropdown then select Export Configuration.
  4. Click Download to save the current configuration of your repositories to a specified location.

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

If you use HTTP/HTTPS URLs in the origin field, the Git add-on 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 add-on configuration instead.

Adding Existing Repositories via Bulk Change

For administrators who have several repositories, the Git add-on 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 add-on 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. Go to cog Administration > Add-ons.  Under Git Integration Plugin for Jira, select Git Repositories.
    helpful tip
    If using Jira 7, go to Administration  > Add-ons. Select Applications on the page tab. Under Git Integration Plugin for Jira on the sidebar, select Git Repositories.
  2. Click Bulk Change dropdown then select Import Configuration.
  3. The following screen is displayed:

    Bulk change import repository config

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

helpful tip
Bigbrassband recommends that you download the example with the full configuration.

Editing Existing Repositories in the TSV File

  1. Navigate to the .tsv file and edit it with your favorite spreadsheet program.
  2. fyi
    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 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.
    fyi
    When importing to a new server, the "id" field must be blank.
    root Optional on existing servers.  See Repository Root in section, Adding a Repository via Advanced Setup.
    fyi
    The "root" field may refer to an existing repository on a new server. If "root" doesn't exist, this field must be blank.
    origin Required.  See Repository Origin in section, Adding a Repository via Advanced Setup.
    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 add-on 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 Optional.  Define a meaningful name for this repository configuration.  If this field is left blank, the default value is obtained from the origin.
    enableFetches 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 in section, Adding a Repository via Advanced Setup. The default boolean value for this field is true.
    revisionIndexing Optional.  See Revision Indexing in section, Adding a Repository via Advanced Setup. The default boolean value for this field is true.
    revisionCacheSize Optional.  See Revision Cache Size in section, Adding a Repository via Advanced Setup. The default value for this field is 10000.
    mainBranch Optional.
    Set specific branch as the main branch for this repository. The default value is "master".
    See Main Branch in section, Adding a Repository via Advanced Setup.
    username, password Optional.  See Use basic http authentication in section, Adding a Repository via Advanced Setup.  Leave blank if 2FA is enabled for the git host.
    pat Optional. Required, if 2FA is enabled for the git host. This field accepts personal access token from supported git hosts.
    gitViewerEnabled Optional.  Setting this field to true will enable the Repository Browser feature for the configured repository.  The default value for this field is false.
    projectMapping 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.
    • 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 Optional.  See the Smart Commits section. If left blank, the default value for this field is true.
    sendCommitEmails Optional.  Send commit notification emails for this repository.  If left blank, the default value for this field is true.
    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.  Default value is 1440 minutes.
    changesetFormat, fileAddedFormat, fileModifiedFormat, fileDeletedFormat Optional.  See the Web Linking section.
    disabled Optional.  Add this repository into the Git add-on configuration and set its status to updated (enabled) or disabled.  If left blank, the default value for this field is false.
    hosted Internal field. Read-only. This field will show whether the repository is hosted on Jira or not.
    tagsFilter 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 Internal field. This field will show whether the repository is a tracked folder, a connected GitLab server or a simple repository.
    trackedFolderId 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 Optional.  Set "delete" on this column/field as a confirmation to the Git add-on to automatically remove the selected repository from the plugin configuration.  If left blank, no changes will occur.
    sshKeyId This is the ID of an associated SSH key.
    limitGitData 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 (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.
    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
    note
    Take note that the .tsv file is verified by the Git add-on 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.
  3. 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 the add-on 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 open in new tab.