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