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

Contact Support
GitKraken Status  

Webhooks – Features

What’s on this page:

 


 

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.

  1. From your Jira dashboard, go to menu Git ➜ Manage repositories. On the sidebar, under Git Integration for Jira, click Webhooks.


  2. 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 GETPOST, 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"
    }
}

 

More articles about webhooks setup

Creating reindex triggers for a single repository

Adding webhooks for GitHub

Adding webhooks for GitLab

Webhooks GitHub Organization support

Adding webhooks for Azure DevOps Repos | VSTS

Adding webhooks for Azure DevOps Server | TFS

Adding webhooks for Bitbucket

Adding webhooks for Gerrit

Have feedback about this article? Did we miss something? Let us know!
On this page