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”

   

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)

   

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

   

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

8. 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!

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.

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:

• 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:

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

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.

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).

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
	The title displayed in the table after the rule has been created.
	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.
	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.
	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.
	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.
	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.
	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.

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.

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:

• 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.

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.

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

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

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).

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

success