« Table of Contents

Bulk Change Jira Server

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

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

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. Go to cog Administration > Applications.  Under Git Integration for Jira, select Git Repositories.
  2. Click  Bulk Change dropdown 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. Go to cog Administration > Applications.  Under Git Integration for Jira, select Git Repositories.
  2. Click Bulk Change dropdown then select Import Configuration.
  3. The following screen is displayed.

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

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. 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.
    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.
    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 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 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 for Jira app 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 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 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
    requireUserPat Require users to specify their own PAT for branch and pull/merge request management.
    sourcesDiffViewEnabled 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.
    apiPath 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 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 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 Optional.  AWS integrations only.  Specify a region for AWS CodeCommit integration.
    For region values, see AWS Regions and Endpoints.
    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.
  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 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 open in new tab.

 

« Table of Contents