Table of contents
- Introduction
- App Requirements
- Getting Started for Git Administrators
- Installation
- Managing License Key
- Working with SSH Keys
- Git URL Ports
- Setting Up Repositories
- Using the Auto-Connect Integration Wizard
- Connecting a Repository via Advanced Setup
- Adding a Repository Hosted on Windows Servers or Windows Network Share
- Tracked Folder and Special Integrations
- Managing Repository/Integration Configuration
- Repository/Integration Project Permissions
- Bulk Change
- Commit Email Notifications
- General Settings
- Web Linking
- Disabling Source and Commits Tabs
- Linking Git Commits to Jira Issues
- Smart Commits
- Repository Browser
- Viewing Commit Code Diffs
- Git User Identity
- Jira User Information Card
- Jira Issue Page
- Jira Project Page
- Jira Developer Panel
- Git Tags
- Reindexing
- JQL Searching
- Webhooks
- Jira Data Center (High Availability and Clustering)
- Localization
- Terms
- Licensing Notice
Documentation
Managing Repository/Integration Configuration
Manage connected repositories or integration via the Actions commands on the git configuration page.
Introduction
After successfully connecting your git repositories or integrating your git host via Git Integration for Jira app, you can change repository settings depending on the connection protocol of the repository or integration.
On the git repository configuration page, you can manage connected repositories and integration such as enabling/disabling repository connection/integration (Jira Server only), edit/update repository/integration settings or disconnect repositories/integrations.
Getting Started
JIRA SERVER / DATA CENTER
JIRA CLOUD
For the repository/integration list, utilize the following references for the items:
Enabled - Enables/disables an integration for use in Jira. For disabled integrations, repository information and function such as commits, pull/merge request, git viewer and etc are not available.
JIRA SERVER DATA CENTER.Location - Displays a short identifier where the integration is located. For example, HOSTED is displayed for self-hosted integration; FOLDER for tracked folder or EXTERNAL for remoted-hosted integration. Some supported git host integration are also displayed here.JIRA SERVER DATA CENTER
Repository / Integration - Displays the repository name, integration name or integration URL.
While you can change the name displayed for this column, some integration names does not allow to be changed.
JIRA SERVER DATA CENTERLast indexed - Shows how long the time the integration was last indexed.
JIRA SERVER DATA CENTERLast indexer check - Shows the date and time the indexing service has checked if the repository should be examined for changes.
JIRA CLOUDFor more information on Jira Cloud indexer, see Jira Cloud: Indexing Explainer.
Status - Shows the index status of the integration.
- It shows UPDATED if Repository Root is configured correctly and the Jira instance can access it.
- For Jira Server/Data Center - It shows DISABLED if the Enabled status of connected repository is unchecked.
- It shows REINDEXING,RUNNING or QUEUED during reindexing of the connected repository or tracked folder/repositories.
- It shows ERROR if the connected repository has connection issues with the configured git host.
Actions - To the right of the Status colum are actions that can be performed for the selected connected repository/integration. Clicking the Actions icon will open a context menu with a set of functions for managing integrations. The Actions sub-menu functions will depend on the type of integration you were working on. For more information, see Managing Integration via Actions for your specific platform: Jira Cloud, Jira Server/Data Center.
Managing Integration via Actions (Jira Cloud)
After integrating your repository or git host, a set of Actions can be performed by clicking the settings icon under the Actions column on the repository/integration configuration list.
Utilize the following actions to manage connected integrations in Jira Cloud:
- Reindex integration - Immediately starts the synchronization with the selected repository.
- Show integration repositories - Opens the Tracked folder dialog to manage repositories for this integration. Clicking on the Last indexer success date/time will reveal indexing information for the selected repository. Clicking on a repository name will open the integration settings for the selected repository. For detailed information on this function, see below.
- Edit integration settings - Opens the page to manage repository settings for the selected integration. See integration and repository level configuration below.
- Remove integration - Disconnects the selected integration and removes its settings from the Git Integration for Jira app repository configuration.
- View log - Opens a dialog showing the indexing log of the selected integration.
EDIT INTEGRATION SETTINGS (JIRA CLOUD)
The repository configuration can be setup using the following methods:
Managing Integration via Actions (Jira Server/Data Center)
After integrating your repository or git host, a set of Actions can be performed by clicking the settings icon under the Actions column on the repository/integration configuration list.
The set of functions depends on what type of integration or repository connection is selected:
EDIT REPOSITORY SETTINGS (HOSTED/EXTERNAL/FOLDER)
This Action opens the Git Repository - Advanced page where you can change the settings of the selected connected repository: HOSTED, EXTERNAL or FOLDER.
Utilize the options below for configuring repository settings:
| Option | Description | Integration |
|---|---|---|
| Display Name | This is the alias that will appear in the Repository/Integration column. | HOSTED, EXTERNAL, FOLDER |
| Absolute Repository Root | This is the calculated absolute path of the clone repository root on the same machine as Jira. | HOSTED, EXTERNAL, FOLDER |
| Clone root location | Set to automatically managed or manually configured by Jira admin. | HOSTED, EXTERNAL, FOLDER |
| Repository Root | This is the path to a clone of the repository. | HOSTED, EXTERNAL |
| Enable Fetches | Set to either hosted at remote server or hosted on the same server as Jira. | EXTERNAL |
| Repository Origin | This is the full URI to the Git origin (from where the repository was cloned). | HOSTED, EXTERNAL, FOLDER |
| Main Branch | Specified branch used when making comparisons for ahead/behind calculations as well as the default branch in selections. 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. When editing or updating repository settings, this field will allow a user to select from a list of available branches to assign as master for the selected repository configuration. 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, the Git Integration for Jira app will check/update the main branch value. This change is reflected in the Repository Settings. In the case of Gerrit, the default main branch is always "master". For repositories within an integration, the main branch can only be changed on the git server. | HOSTED, EXTERNAL |
| Use HTTP(S) Authentication | If this repository connection supports HTTP(S)) authentication, you may enter required credentials here. | EXTERNAL |
| SSL Verify | Enable/Disable. If set to disabled, the Git Integration for Jira app will ignore verification of SSL certificates when connecting to a remote Git server. | EXTERNAL |
| TrustFolderStat | 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 setting for Jira Server is True. For Jira Data Center, it's False. If your repository or JIRA HOME is stored on a network share, it is highly recommended to set this setting 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. | HOSTED, EXTERNAL, FOLDER |
| > Advanced: Revision Indexing and Fetch refspec | Revision Indexing – This setting turns on the memory cache which is used when list of commits are displayed. Set if revision indexing will index and link to any mentioned issue keys in the revision history or not. Fetch refspec – Git refspecs contains patterns mapped as references from the remote to the local repository. The first two refspec options are required. The rest of the options are optional. For more information, see Git Internals -- The Refspec | EXTERNAL, FOLDER |
| Repository Browser | Enabled/Disabled. When enabled, it allows users to view Git repositories of configured projects. For more information, see Repository Browser. | HOSTED, EXTERNAL, FOLDER |
| Tags | Set whether to show all tags or show on tags with matching regex pattern. For more information on git tags, see Git Tags. | HOSTED, EXTERNAL, FOLDER |
| Project Permissions: Restrict to projects | The default setting is Associate with all projects. You can restrict access to the Repository Browser and Git Commit tabs (Advanced) for the selected repository by setting the project associations. For more information, see Setting Up Repositories: Project Permissions. | HOSTED, EXTERNAL, FOLDER |
| Source Code Diff Viewing | Allows users to view the diff by commit and file. | HOSTED, EXTERNAL, FOLDER |
| Smart Commits | Allows the users to use the smart commits feature. | HOSTED, EXTERNAL, FOLDER |
| Commit Message Validation | Turn the setting on to reject/ignore any commit that does not reference a valid Jira issue key. | HOSTED |
| Commit Notification Emails | Enable/disable this setting to allow sending of commit notification emails. Set the Max commit age (in minutes) as desired. Commit notifications will be e-mailed if the age of the commit is less than or equal to this value. | HOSTED, EXTERNAL, FOLDER |
| Web Linking | Optional. The web linking feature adds links to your git hosting provider directly into the Git Commits tab. For special integrations (Auto-Connect), this feature is configured automatically. For more information on about this topic, see Web Linking. | EXTERNAL |
The tracked folder and auto-connect integrations can be configured using the following methods:
- Integration level – Click Actions > Edit integration connection settings. This will open the settings for the selected integration.
- Repository level – Click Actions > Show integration repositories. Click a repository from the list to open the settings for the selected repository.
DEFAULT BRANCH
Most git integrations allow changing of the default branch of the repository/project other than "master" at server level. This change is reflected in the Repository Settings.
For Auto-connected integrations, the Git Integration for Jira app will check/update the main branch value from the git server and will override the repository setting on each reindex. In the case of Gerrit, the default main branch is always "master".
Show Tracked/Integration Repositories
On the Manage Git Repositories page, click the icon under the Actions column then select:
- For tracked folders – Show tracked repositories.
- For auto-connect integrations – Show integration repositories.
This action will open the Tracked Folder dialog showing the tracked/integration repositories:
Browse the tracked repositories/folder by clicking the page controls (if more than 10 repositories are connected).
v2.13.1+ In the filter field at the top right, enter a character or a name to display repositories that contains the search text.
Enable/disable the state of the connected repositories under the Enabled column.
JIRA SERVER DATA CENTEREdit Integration Connection Settings
Clicking Actions > Edit integration connection settings opens the configuration page for integration connection settings.
Utilize the following options to configure the selected integration:
| Option | Description |
|---|---|
| Display Name | This is the alias that will appear in the Repository/Integration column. |
| Personal Access Token | If the PAT has expired or changed, enter the new PAT on the provided box. |
| SSL Verify | The Git Integration for Jira app will enforce/ignore verification of SSL certificated when connecting to a git server. For more information, see SSL Verify |
| TrustFolderStat | 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 setting for Jira Server is True. For Jira Data Center, it's False. If your repository or JIRA HOME is stored on a network share, it is highly recommended to set this setting 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. |
| Custom API Path | The Git Integration for Jira app supports this feature for GitHub and GitLab integrations. For more details, see Working with Custom API Path. |
| JMESPath Filters | JMESPath is a query language for JSON used to filter API results and to limit which repositories are integrated. For more information, see Working with JMESPath Filters. |
| > Advanced: Revision Indexing and Fetch refspec | Revision Indexing – This setting turns on the memory cache which is used when list of commits are displayed. Set if revision indexing will index and link to any mentioned issue keys in the revision history or not. Fetch refspec – Git refspecs contains patterns mapped as references from the remote to the local repository. The first two refspec options are required. The rest of the options are optional. For more information, see Git Internals -- The Refspec. |
Edit Integration Feature Settings
Clicking Actions > Edit integration feature settings opens the configuration page for integration features settings.
Utilize the following options to configure the selected integration:
SSL Verify
The SSL Verify option is set to Enabled by default. If set to disabled, the Git Integration for Jira app will ignore verification of SSL certificates when connecting to a git server.
In the above example, the Repository Settings screen from Jira Cloud is shown.
Commit Message Validation
This option is only available for self-hosted git servers. For example, you are hosting your git repositories in your own server such as GitLab CE/EE or GitHub Enterprise. If a developer tries to push a commit without the issue key in its message, the push is rejected by the Git add-on.
If this option is enabled, the commit messages are validated according to the following rules:
- The commit message contains at least one issue key.
- The issue key is valid.
- The issue key exists.
View Repository Properties
Click the view icon to see repository details:
Status - This is the repository connection status.
- It shows UPDATED if Repository Root is configured correctly and the Jira instance can access it.
- JIRA SERVER/DATA CENTER It shows DISABLED if the Enabled status of connected repository is unchecked.
- It shows REINDEXING,RUNNING or QUEUED during reindexing of the connected repository or tracked folder/repositories.
- It shows ERROR if the connected repository has connection issues with the configured git host.
Last Indexed - This is the date and time when synchronization was last executed.
Repository Root - This is the local path to the repository on the server where your Jira service is running.
Repository Origin - This is the URL to the hosted git service used on the project.
Changeset, File Added, File Modified, and File Deleted formats - Displays the weblinking format strings (if set in the repository weblinking configuration).
Removing a Repository Configuration
Delete a repository if it isn't needed or is broken in the Git Integration for Jira app configuration.
- On your Jira Server/Data Center dashboard, go to Administration > Applications. Under Git Integration for Jira on the sidebar, click Git Repositories.
For Jira Cloud, go to Jira Settings > Apps > Manage Git repositories.
Alternatively, the git repository configuration page can also be accessed via Dashboard menu Git > Manage (Git) repositories. - Click Remove repository under the Actions column for the selected repository.
- The confirmation screen is displayed. Uncheck the Delete repository files... option to retain git repository files in the displayed path or leave it checked to also delete the repository files from the displayed path.
- Click to remove the repository. Click to abort this process.
