Skip to main content
Skip table of contents

Cloud (Forge App)


What is the Jira Hooks for Bitbucket Plugin?

The Jira Hooks for Bitbucket plugin is designed to integrate Jira with Bitbucket. Its primary goal is to verify the integrity of branches, pull requests, and commits in relation to their corresponding Jira issues. In many cases, multiple aspects of a related Jira issue must be checked before an integration merge can proceed.

This project aims to provide a set of hooks that ensure issue consistency before an action is performed. To maintain integrity between branches, pull requests, commits, and their related Jira issues, the plugin offers a Merge Hook with various checks to enforce issue tracking and maintain a structured Git workflow.


How to install

Jira Hooks for Bitbucket is a Forge app that can be installed directly into your Bitbucket Cloud workspace. It enhances the integration between Jira and Bitbucket by automatically linking commits, branches, and pull requests to Jira issues—making it easier to track development activity from within Jira.

This guide walks you through installing the app in Bitbucket Cloud via a secure installation link provided by Atlassian.

Installation Steps

  1. Sign in to Bitbucket

    Log in with your Bitbucket Workspace

  2. Open the Installation Link

    Click or copy-paste the following link into your browser (it can take some seconds to load the page):

    👉 Install Jira Hooks for Bitbucket

  3. Review Permissions

    The app will request access to certain data (e.g., repositories, pull requests).

  4. Click “Get app”

    Start the installation via the Button “Get app”

    JiraHooksInstallation.png
  5. Choose a Workspace

    Select the workspace where you want to install the app

  6. Click “Install”

    Confirm the installation by clicking the Install button.

  7. Enable Custom Merge Checks

    The next step is to enable Jira Hooks for Bitbucket as a custom merge check. You can enable the custom merge check globally or per repository. (e.g. https://bitbucket.org/<your-workspace>/workspace/settings/merge-checks)

    custom-merge-check.png

    Please configure the check for all branches, and if you are using a Bitbucket Premium version, you can also mark this check as Required.

    custom-merge-check-configuration.png

    Configure Custom Merge Check

To use Custom Merge Checks in a way that blocks pull requests, you must have a Bitbucket Premium plan.

The app Jira Hooks for Bitbucket cannot override or change this behavior, as it is a limitation set by Atlassian’s licensing model.

For more details, see Atlassian’s official documentation:

🔗 Set up and use custom merge checks – Atlassian Support

  1. Configure the App

    Follow this document to configure the app


Rule-functions

The add-on operates with user-configurable rules. Each rule defines the criteria that must be met before a merge can proceed. Users can create multiple rules, allowing each criterion to be enforced with a dedicated rule. This improves clarity by keeping all rules organized in specific configurations, making it easier for developers to identify what went wrong.

How to create such a rule is explained in the chapter Configuration of the Rules.

It is possible to create both Workspace Rules and Repository Rules. Workspace Rules can be inherited by all repositories within the workspace, allowing managers to define rules that apply to multiple repositories. As soon as someone modifies a Workspace Rule, the changes are automatically applied to all repositories using that rule.

All created rules contain a title and an error message, making it easier to identify them in the results section. This section displays the rule's title, and if desired, also the error message and an optional hint. Additionally, it provides more information about the data collected during the checks.

During rule creation, the following checks are available for selection:

All of the following functions can be activated or deactivated!

Name

Description

Search settings

Allow searching in commit messages

It can only search issue keys inside the commit messages if this checkbox is selected

Allow searching in branch name

It can only search issue keys inside the branch name if this checkbox is selected

Allow searching in pull request title

It can only search issue keys inside the pull request title if this checkbox is selected

Allow searching in pull request description

It can only search issue keys inside the pull request description if this checkbox is selected

Issue-key check

At least one commit must contain a valid issue key

A merge can only be done, if at least one commit of a push contains valid issue key reference.

Each commit must contain at least one valid issue key

A merge can only be done, if all commits of a push contains a valid issue key reference.

All issue keys found in one commit message must be valid

A merge can only be done, if all issue keys in a commit message are valid.

All issue keys found in one commit message must match the issue key found in the branch name

A merge can only be done, if all issue keys in a commit matches the issue key found in the branch name.

Branch must contain valid issue key

A branch can only be merged if the name contains a valid issue key.

Pull request title must contain a valid issue key

A branch can only be merged if the pull request title contains a valid issue key.

Pull request description must contain a valid issue key

A branch can only be merged if the pull request description contains a valid issue key.

JQL check

All issue-keys

All found issue references must match the given JQL

One issue-key

At least one issue reference must match the given JQL

Naming convention

Commit-messages

The commit-messages must match the expected regular expression

Branch-name

The branch-name must match the expected regular expression

Pull-request-title

The pull-request-title must match the expected regular expression

Pull-request-description

The pull-request-description must match the expected regular expression

Configure branches

Source-branch

The rule is checked only if the source branch matches the regular expression.

Exclude source-branch

The rule is checked only if the source branch does not match the regular expression.

Destination-branch

The rule is checked only if the destination branch matches the regular expression.

Exclude destination-branch

The rule is checked only if the destination branch does not match the regular expression.


Configuration of the Jira Connection

Before getting started, generate an API token to authenticate with Jira. Visit https://id.atlassian.com/manage-profile/security/api-tokens and follow the provided instructions.

Afterward, you can create a Jira instance either within the repository settings (Repository Settings → Jira Hooks for Bitbucket), applying it to just that repository, or within the workspace settings (Workspace Settings → Jira Hooks for Bitbucket), making it available for all repositories in the workspace.

connectionTableEmpty.png

The Jira Connections tab is used to create new Jira connections.

Create Repository Jira Connection

When you click the Create New Connection button, a popup will appear, allowing you to configure your Jira connection. The popup includes the following fields that need to be completed with your information:

connectionEmpty-20250320-090526.png
  • Enter the Email that is used for the Atlassian products

  • Enter the URL of the Jira instance that needs to be connected.

  • Enter the API-Token that has been created earlier

Once all the text fields are filled, it should look something like this:

connectionFullBlurr.png

Click the “Submit” button to create the connection. If the creation was successfully it will show up in the list of Jira Connections.

connectionTableFullBlurr.png

Once the first Jira connection is created, you have several options to proceed. You can either create additional Jira connections (at the workspace or repository level) or start setting up the first rule for the merge check (also at the workspace or repository level).

It’s possible to configure multiple Jira connections, and when multiple connections are added, the system will search for issue keys across all the provided connections.

The connections are processed sequentially from top to bottom. Their order can be rearranged within the table to adjust the processing sequence. As soon as all issue keys are found, the loop terminates, and the checks proceed.

Workspace Jira Connection

Similar to Workspace Rules, Workspace Connections can also be created. These allow the creation of Jira connections for the entire workspace. While they can be enabled or disabled directly in the repository settings, they cannot be edited or deleted there. To manage workspace connections, a table is provided below the repository connections. This table includes a toggle switch for each connection, allowing users to enable or disable connections as needed.

workspaceConnectionFullBlurr.png


Configuration of the Rules

To create a new rule, click the Create New Rule button. This opens a popup where all rule settings can be configured. Similar to connections, rules can be configured at both the repository level (Repository Settings → Jira Hooks for Bitbucket) and the workspace level (Workspace Settings → Jira Hooks for Bitbucket).

ruleTableEmpty.png

Create Repository Rule

The following fields can be configured for each rule.

All checkboxes are disabled by default and cannot be selected. To enable them, the appropriate toggle must first be switched on. Once the toggle is activated, the checkboxes can then be selected.

Check

Explanation

ruleTitle.png

The title displayed in the table after the rule has been created.

ruleSearchSettings.png

The Search Settings check defines where the system should look for issue keys in your commit messages, branch names, pull request titles, and pull request descriptions. It allows you to configure which parts of your code and metadata should be searched for issue keys.

ruleIkCheck.png

The Issue Key check ensures that the commit messages, branch names, pull request titles, or pull request descriptions include one or more valid Jira issue keys.

Since this check relies on issue keys to function, the corresponding search setting checkboxes must be enabled.

Since the "All issue keys found in a commit message must match the issue key in the branch name" check relies on the "Branch name should contain a valid issue key" checkbox, the branch checkbox must be clicked first in order to enable the other.

ruleJqlCheck.png

The JQL check (Jira Query Language check) verifies whether the issue keys in commit messages, branch names, pull request titles, or descriptions match a specific JQL query.

Since this check relies on issue keys to function, at least one of the search setting checkboxes must be enabled.

ruleNcCheck.png

The naming convention check ensures that the names of branches, commit messages, or pull requests follow a specified pattern or set of rules. This can include checking for specific prefixes (like feature/, bugfix/, etc.), formatting requirements (such as lowercase letters, hyphens instead of spaces), or the inclusion of relevant issue keys (e.g., PROJECT-123) in the names.

ruleConfigBranches.png

The configuration of branches verifies whether the source and destination branches match a specified regex or exclude regex pattern. If either the source or destination branch matches the defined pattern, the rule is either applied or skipped based on the configuration.

ruleMessaging.png

The error message shown in the error message section is generated by the merge check when an issue occurs.

Th hint provides a more detailed version of the error message, allowing for additional context to be included.

Once the first Rule is created, you have several options to proceed. You can either create additional Rules (at the workspace or repository level) or start the first merge check.

ruleTableFull.png

This product allows you to create multiple rules, enabling you to design exactly the rule needed for a specific use case. All rules can be turned on or off directly within the table where they are stored. Additionally, the sequence of the rules can be easily adjusted by dragging a rule to a different position. This also represents the execution sequence of the rules. While they are executed asynchronously, the results are displayed in the specified order.

Workspace Rules

Workspace Rules can be enabled or disabled directly in the repository settings, but they cannot be edited or deleted there. To manage workspace Rules, a table is provided below the repository Rules. This table includes a toggle switch for each Rule, allowing you to turn the Rule on or off as needed.

workspaceRuleFull.png


Advanced Settings

Once the rules and Jira connections are set up, additional settings can be configured. A dedicated tab is available for defining the regular expression for issue keys and specifying an escape character to exclude certain issue keys. These settings are applied globally and affect all rules.

The following fields need to be filled:

advanced.png
  • Enter an escape character

  • Enter an issue key regular expression

The escape character allows specific issues to be ignored.

The issue key regular expression defines the pattern for issue keys.

Overwrite Workspace Advanced Settings

Within each repository, you can define whether the settings from the workspace should be overridden or if the repository-specific settings should be used.

advancedWorkspace.png


How does it have an affect?

If any of the configured checks evaluate to false, the merge will either be blocked or a warning will be displayed, along with the provided message. Whether you receive an error or a warning depends on your app configuration, where you can choose between Off, Recommended, and Required.

The Required option is only available to Atlassian premium users.

In contrast to the data-center version, the cloud version does not include a commit check. The API does not provide an option to refuse a commit if the expected criteria are not met.

The add-on includes two types of triggers. The first is the PRE-MERGE type, which includes the on-code-pushed trigger that runs the check after each code push to the branch. The second type is the ON-MERGE type, which includes the on-merge trigger that runs the check after each merge attempt.

appConfig.png

After the initial check is performed, you will see either a success message or an error message. The error message might appear as follows:

checkFailedMessage.png

Attempting to merge despite the issue will trigger a popup, either preventing the merge or displaying a warning, depending on the selected option.

mergeDisabled.png


Results

This section displays the results of the rules. After a merge check, once all rules have been evaluated, a field appears summarizing how each rule performed. Each rule is represented by a row containing its title, a button, and an icon indicating the result (success or failure).

allResults.png

The button provides additional details about the rule's outcome. When clicked, it opens a popup displaying an error message and, if available, a hint. The popup also provides information on why the rule passed or failed, helping users identify what went wrong and address the issue effectively.

fail

failResult.png

success

successResult.png

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.