Git Integration for Jira Self-Managed (Data Center/Server) Documentation

Webhooks – Features

What’s on this page:

What are webhooks and why use them?
Do I need to set up webhooks?
Getting started
Advanced settings
GitHub/GitLab push events
More articles about webhooks setup

What are webhooks and why use them?

Webhooks can be an extremely powerful tool that can be configured to trigger an immediate re-index of your repositories from remote systems. Your git server can send this near real-time data to Jira when your git data changes. This results in much faster indexing time so that you don’t have to wait for the regular polling interval (see General settings).

Webhooks can be triggered whenever certain actions are performed. For example, you can configure a webhook to execute when:

a new commit is pushed
a pull request is opened
a branch is merged

You can create webhooks for individual repositories or most git providers will allow you to create webhooks at an account-level or org-level.

Do I need to set up webhooks?

Short answer is no, the regular reindexing configured in General settings by the Jira administrator is the base requirement for indexing. However, by configuring webhooks to trigger reindexing, Jira will more often have up-to-date information. The normal frequency of the app limits this by polling at set intervals.

Without webhooks, you will rely on the default polling of the app which is unchangeable by non-Jira administrators. Jira users will have to wait for the default interval for updates which means users will not see new commits or pull requests until the next indexing interval.

Getting started

IMPORTANT!
To use the webhooks feature, it must be enabled in the Manage (Git) repositories page.

Configure webhooks to trigger immediate reindex of your repositories from remote systems.

From your Jira dashboard, go to menu Git ➜ Manage repositories. On the sidebar, under Git Integration for Jira, click Webhooks.
Enable/disable the webhook feature by clicking on the Enabled/Disabled option.

Copy the webhook URL to the system clipboard by clicking the copy icon adjacent to the right. Use this URL when required by the repository web hooks setting of your git host.

The Secret Key is a secure random-generated alphanumeric string at the time of the Git Integration for Jira app installation. The user can change this to a different value by generating another secret token according to your Git host.

Use this key in the form of:

<JIRA_BASE_URL>/git/webhook/reindex/<SECRET_KEY>

Assign your Jira base URL and Secret Key to the sample URL structure

Example:

https://jira.yourorg.com/rest/gitplugin/webhook/1.0/reindex/sdf34tGdfgGDG345g3y0045TYG23te37

All the repositories will be reindexed if the URL specified above is activated through GET, POST, or PUT and the webhooks are enabled.

There is no support for other HTTP methods such as DELETE or HEAD.

Advanced settings

The advanced options provide a couple of settings for webhook indexing performance improvements.

Ignore unmatching webhooks

Continuous reindexing of all repositories may cause significant performance issues if unmatching webhooks are not ignored. When set to Enabled (default), this setting filters out incoming webhooks without a matching repository. This setting is Enabled by default for new and upgrading users.

Min. repository reindex interval

IMPORTANT! v4.23+ uses seconds as unit value. Pre-v4.23 uses minutes.

The frequency of reindexing is set this value (in seconds). Default value is 0 seconds. Upgrading the plugin does not change the value for this setting. For new users, the default value is 3 seconds.

GitHub or GitLab push events

The Git Integration for Jira app supports GitLab and GitHub push event to define individual repository to index.

The webhook parses the following payload formats:

GITHUB (Introduced v2.7.10)

{   
    "repository": {   
        "git_url": "git://github.com/testuser01/test-repo.git",
        "ssh_url": "[email protected]:testuser01/test-repo.git",
        "clone_url": "https://github.com/testuser01/public-repo.git",
        "svn_url": "https://github.com/testuser01/public-repo"
    }
}

GITLAB

{   
    "repository": {   
        "git_ssh_url": "[email protected]:testuser01/test-master.git",
        "git_http_url": "https://gitlab.com/testuser01/test-master.git"
    }
}