Bitbucket and Jira Integration: A Step-by-Step Guide [2026]
Hard to trace code changes to Jira issues? Learn bitbucket and jira integration step by step to keep work visible. Read now.
When Bitbucket and Jira aren’t connected, code changes can be hard to trace back to the work that requested them. A commit lands, a pull request opens, and teammates still have to ask which Jira issue it belongs to.
That uncertainty slows reviews and makes release tracking harder. A missed issue key or permission setting can also leave your team thinking the integration is broken. But here’s the truth: connecting the products is only part of the job. Your team also needs consistent issue references and a quick way to check that activity appears in Jira. Here’s how to connect Bitbucket and Jira, link development work to issues, and troubleshoot common problems. You’ll also see how to build habits that keep the connection useful after setup.
How to set up Bitbucket and Jira integration
Start by connecting the Bitbucket workspace to Jira, then add Jira issue keys to your development activity. The exact menus can vary by Jira edition and configuration, so look for the Code feature or the product connection settings available to your administrator.
-

Check your accounts and permissions
Confirm that you can access the Jira site and Bitbucket workspace you intend to connect. You may need Jira administration permissions to configure a product connection, plus workspace access in Bitbucket.
Check that your teammates can also view the relevant Jira projects and Bitbucket repositories. A connection can work for an administrator while remaining invisible to people who lack permission to one side.
Open Jira’s development connection settings
In Jira Cloud, open the relevant project and check whether its Code feature is enabled. If you see an option to connect Bitbucket, follow that prompt and select the workspace your team uses.
If the project does not offer that route, ask a Jira administrator to check the site’s product connection settings. Depending on your setup, the connection may be managed centrally rather than within an individual project.
-
Authorize the Bitbucket workspace
Follow the authorization prompts and review which workspace and repositories Jira can access. Choose the workspace that contains the repositories your Jira project needs to display.
Do not approve a connection under an account that lacks ongoing administrative ownership. An accountable administrator can review access later and help resolve permission changes.
Confirm the connection in Jira
Return to the Jira project and look for its Code area or development activity panel. If the connection is successful, Jira should be able to show linked commits, branches, or pull requests when they reference an issue.
If the panel is empty, that does not necessarily mean the connection failed. You may need to create a branch or commit with a valid Jira issue key before development activity appears.
-
Include the Jira issue key in development work
Use the issue key, such as PAY-214, in branch names, commit messages, and pull request titles. For example, name a branch feature/PAY-214-checkout-retry and start a commit message with PAY-214.
Use the same key consistently. A typo, missing project prefix, or outdated issue number can stop Jira from associating the activity with the right issue.
-
Try the connection with a test issue
Create a small test branch or commit tied to an issue you can safely use. Open that issue in Jira and check whether the development activity appears.
Then open the corresponding branch or pull request in Bitbucket. Confirm that the issue key is visible and that teammates with the right permissions can see the related activity.
Share a team convention
Agree on where issue keys belong and make the convention part of your team’s normal workflow. For example, require keys in branch names and pull request titles, even when a commit already has one.
A short naming rule prevents inconsistent references across repositories. It also gives reviewers a fast way to understand why a change exists.
What Jira can show from Bitbucket activity
Once the connection recognizes an issue key, Jira can display development activity associated with that issue. Depending on the products and configuration you use, that activity may include branches, commits, pull requests, and deployment information.
Here’s why: the issue key acts as a link between the planned work and the engineering activity. If Jira issue PAY-214 appears in a branch name and pull request title, teammates can follow the change from the issue without searching repositories manually.
For example, a product manager can review the Jira issue to see whether a pull request is open. A developer can start from the same issue and check which commit or review relates to the requested change.
Use issue keys and Smart Commits carefully
Issue keys make the basic connection useful, but consistent formatting matters. Agree on one pattern, such as placing the key near the beginning of each branch name and pull request title. A branch like bugfix/OPS-82-timeout-message is easier to scan than a vague name such as fix-timeout.
You might be wondering: can a commit do more than link to an issue? Jira Smart Commits can support actions such as adding a comment, recording work, or transitioning an issue when the feature is enabled and the user has permission.
For example, a supported Smart Commit may use a command such as OPS-82 #comment Added timeout handling. Check the syntax and workflow rules for your Jira setup before relying on commands. A requested transition can fail if the target status is unavailable to that user.
Verify the workflow before relying on it
Test the full path, not just the authorization screen. Create a branch with a valid issue key, make a commit, open a pull request, and confirm the expected activity appears in Jira.
Then test with a teammate account that has ordinary project permissions. This catches access gaps that an administrator’s account may hide. If a developer can see the pull request in Bitbucket but not its Jira issue, review project and repository permissions on both sides.
For teams that use Bitbucket Pipelines, check whether deployment activity is available in the Jira development panel after the connection is configured. A release issue can then show more of the path from implementation to deployment, subject to your setup and permissions.
Keep the connection secure and maintainable
Grant access only to the workspace and projects that need to work together. Review administrators and connected accounts when team ownership changes, and remove access that is no longer needed.
Keep your naming convention short enough that people will follow it. For instance, asking developers to put the issue key in a branch name and pull request title is usually easier to check than maintaining a long set of special cases.
Also decide who owns troubleshooting. A clear point of contact can check authorization, project access, and issue-key formatting before the team changes workflows unnecessarily.
A project and knowledge management option: ONES.com
Value proposition: ONES.com brings project management and knowledge management together in one platform, powered by ONES Assistant. ONES Project and ONES Wiki are sold separately, so teams can choose the product that fits their needs.

ONES.com is relevant when your team is reviewing how it manages work and engineering knowledge alongside development activity. It does not replace Bitbucket as a code hosting service, and this guide does not claim a native Bitbucket connection. You can keep Bitbucket for repositories while evaluating whether a different project and knowledge workflow suits your team.
Core capabilities
- Scattered project tracking: When work is spread across inconsistent processes, ONES Project provides Jira-compatible workflows. The result is a more familiar way to organize issues and coordinate delivery.
- Rigid work stages: When teams need different approval or delivery paths, custom workflows let them shape how work moves. That can make project tracking fit the team’s process more closely.
- Limited issue detail: When default issue fields miss important context, custom fields capture the information your team needs. Teams can make work easier to review without relying on extra plugins for every adjustment.
- Unclear sprint progress: When sprint work is difficult to monitor, sprint management and built-in reporting help teams review progress. That gives team leads a clearer view of delivery work.
- Repeated manual actions: When routine task handling takes time, automation can handle configured workflow actions. That leaves more time for review and problem-solving.
- Too many add-ons: When a team depends on multiple plugins for everyday project needs, native capabilities can reduce plugin reliance. Fewer dependencies can make administration easier.
- Separate project and knowledge spaces: When teams want project management and knowledge management from one provider, ONES Project and ONES Wiki offer those distinct capabilities. They are sold separately, so you can select them independently.
- Deployment constraints: When cloud hosting does not meet operational requirements, ONES.com offers Cloud, On-Premise, Private Cloud, and Air-gapped deployments. The self-hosted version has feature parity with the cloud version.
Application scenarios
Growing engineering team: A team that has outgrown simple task tracking can use ONES Project for sprints, custom workflows, fields, automation, and reporting. Developers can continue managing repositories in Bitbucket while the team evaluates its project-management process separately.
Restricted network environment: An organization that needs an air-gapped or self-hosted deployment can consider ONES.com’s deployment options. It can assess project and knowledge management requirements while keeping its code-hosting arrangements distinct.
Teams reviewing Jira workflows: A team looking for a Jira alternative can assess ONES Project’s Jira-compatible workflows and native capabilities. ONES.com offers a free plan for up to 30 seats, giving teams a way to evaluate its project-management fit.
Common challenges and practical fixes
- No development activity appears in Jira: Check that the right Bitbucket workspace is connected, the Jira issue key is valid, and the repository is within the authorized workspace. Then confirm that the person viewing the activity has access to both products.
- Activity appears for some teammates but not others: Review project and repository permissions for each affected person. Test with an account that has the same access level as the teammate experiencing the problem.
- A pull request does not link to the issue: Add the correct issue key to the pull request title or branch name, then check for typos and confirm the issue still exists. Allow time for activity to refresh before repeating the setup.
- A Smart Commit action does not run: Confirm that Smart Commits are enabled, the command syntax is supported, and the person making the commit can perform the requested action. Check whether the target workflow status is available to that person.
- The setup screen differs from the guide: Jira and Bitbucket menus can vary by edition and site configuration. Ask an administrator to locate the current product connection settings rather than repeatedly searching for a menu that may not exist in your setup.
Frequently asked questions
Does Jira automatically link every Bitbucket commit?
No. Jira needs a way to associate development activity with an issue, and the usual method is including a valid Jira issue key in a branch name, commit message, or pull request title. A commit without a recognizable key may not appear on the relevant issue. Use a shared naming convention and test it with a real issue before expecting every change to display automatically.
Can I connect one Bitbucket workspace to multiple Jira projects?
That can be possible, depending on your site configuration, permissions, and how the connection is managed. The important step is confirming that each intended Jira project can access the relevant development activity. Ask your Jira administrator to review the workspace connection and project access, then test the setup with an issue from each project.
Why is my Bitbucket pull request missing from Jira?
Start by checking whether the pull request title or its branch contains the correct Jira issue key. Then confirm that the workspace is connected and that you can access both the Jira issue and Bitbucket repository. A misspelled key, permission restriction, or connection to the wrong workspace can prevent the activity from appearing. Test with a fresh pull request if you need to isolate the cause.
Can Smart Commits transition Jira issues?
Smart Commits may support issue transitions when the feature is enabled and the command, workflow, and permissions allow the action. The transition name must match a status available to the person making the commit. Start with a test issue and verify the result in Jira before using the command across a team. If the transition fails, check the workflow and the user’s permissions.
Does Jira display Bitbucket deployment activity?
Jira may display deployment information when the relevant products and deployment configuration are connected. Teams using Bitbucket Pipelines should verify that their particular setup reports the activity to Jira and that viewers have the necessary access. Run a test deployment tied to an issue, then check its development activity panel instead of assuming deployment details will appear automatically.
Conclusion
Connecting Bitbucket and Jira gives your team a way to trace development work back to the issues that describe it. Start with workspace authorization, use valid issue keys in branches and pull requests, and test visibility with regular team permissions.
But here’s the truth: a connection cannot fix inconsistent habits on its own. Set a naming rule, assign someone to review access, and troubleshoot from the issue key outward. That keeps the integration useful as your team ships changes and gives everyone a clearer view of how planned work becomes code and releases.