6 Tips Before and After Integrating Jira Software With Bitbucket

What do coffee and donuts have in common with Jira Software Server and Bitbucket Server? Together, they make for a great experience, and I’d even go as far to say having one without the other is a bit unsatisfying. We at Atlassian know the ins and outs of coffee and don– er… I mean Jira Software and Bitbucket because we use them together every day to take the busy-work out of our workflows.

Teams that use both tools should definitely integrate them (it’s a pretty straightforward process). When you do, you unleash a powerful set of features that make life easier both for admins and end users. In addition to the detailed info in our documentation, there are some higher-level things to keep in mind so you get the most out of the integration.

Before Integration: What You Need to Know

1. You can use a single instance of Bitbucket Server or Data Center to support your entire organization, even if you have multiple Jira Software Server instances. 

Bitbucket Server and Data Center are highly scalable and can natively integrate with multiple Jira Software instances at once. Your team can get to know Bitbucket and adopt common version control practices without being under pressure to consolidate project management tooling at the same time.

Remember to encourage unique project names across your various Jira instances. If by chance you have , Bitbucket will honor the integration marked as the ‘PRIMARY’. Learn more here.

2. Permissions are permissions are permissions.

Jira Software and Bitbucket are structured in similar ways, not only in data architecture, but also with security enforcement for easier maintenance and admins’ peace of mind. For example, let’s say you have permissions schemes in Jira Software which prohibit particular users from transitioning certain issues. Let’s also say those users have access to Bitbucket (where you can also transition issues, thanks to the integration), but you’ve not set up the equivalent permission scheme there.

No worries. Jira Software and Bitbucket honor each other’s permissions. In this case, those users would be blocked from transitioning those issues via Bitbucket. Likewise, if a Jira Software user isn’t granted access to your Bitbucket instance, then they won’t be able to view linked Git commits, branches, or pull requests from inside Jira Software.

3. Issue keys + branches + commits = traceability and visibility

Issues keys are literally the key to using Jira and Bitbucket as an integrated pair. Including the relevant issue key in your branch names (e.g., “feature-DEV-12345”) and commit message creates a bi-directional link between the pieces. So when viewing an issue in Jira Software, for example, you’ll be able to see all the commits and branches associated with that issue key, and vice versa when you’re in Bitbucket.

Using a branch-per-issue model is the easiest way to bake this into your workflow. Inside each Jira Software issue, you’ll see a “Create branch” button, which – you guessed it – steps you through creating a branch in Bitbucket, with the issue key already incorporated into a suggested name for the branch.

Teams that absolutely require full traceability (audits, anyone?) often use a Git hook that verifies there’s an issue key in each commit message and each branch and rejects them if there isn’t. If writing a custom Git hook isn’t your thing, there are several available in the Atlassian Marketplace.

After Integration: Get the Most Out of Your Tooling

Jira and Bitbucket integrate in so many nifty little ways even we have a hard time remembering them all. To get the most out of these tools, make sure you’re doing these three things.

1. Create a workflow that’s right for your team.

With the combination of Bitbucket Server and Jira Software Server, you can customize branching models, workflow triggers, and Git hooks to create a workflow that makes sense for individual teams, while enforcing company-wide standards like permissions and restrictions.

Branching model – You can specify branch types and their naming conventions for your Bitbucket Server instance. For example, you may decide to select branch types feature, bugfix, hotfix, and release as well as a default prefix. Once that’s set up, whenever you go to create a new branch from an issue, Jira Software will pre-populate branch name and type based on the issue type and your branching model settings. So if the Jira Software issue type is “bug”, the branches you create from it will default to your bugfix naming convention. Oh yeah.

Workflow triggers – These are rules that automatically transition Jira Software issues from one status to another when a certain event occurs: upon pull request creation, a new commit, or similar. This means teammates and stakeholders always see an up-to-date status, even if developers are heads-down coding away.

Merge restrictions and Git hooks — It’s easy to configure rules that prevent users from merging or pushing code if a particular requirement is unmet. Bitbucket Server ships with several – like requiring green CI builds, or all commits be GPG signed – but you can add your own as well. Any custom rule or requirement in your development flow can be solved by a custom merge restriction, Git hook, or even a webhook. It’s all about making your workflow work for you.

Don’t reinvent the wheel, the Atlassian Marketplace has over 250+ add-ons and hooks for 

2. Make changes to Jira issues on the fly, in the context that best fits your role.

For the developers out there, there’s nothing worse than being in the zone, only to have your flow interrupted. Luckily, the Jira-Bitbucket integration helps you take care of project overhead tasks like looking for, transitioning, adding comments to, or creating new Jira Software issues.

Repository shortcuts and linked Jira issues in Bitbucket Server – Clicking on a linked Jira issue key within Bitbucket Server brings the Jira Software issue up on your screen dialog, with all its information and the ability to transition it right then and there. Likewise, repository shortcuts offer links at the repository level to any related asset, like a Jira Software board, Confluence space, Bamboo plan, or whatever else is important to you.

Smart commits – By supplying a special command in your commit message, you can comment, transition, and even record time against related Jira Software issues without ever leaving your terminal window.

Creating a Jira issue from inside a pull request – Spot some code that needs refactoring during a pull request? Create a Jira Software issue to track that work directly from your pull request comments inside of Bitbucket.

3. Get to know the release hub.

To all the product managers, release managers, and other stakeholders out there, the Release Hub is your friend. If your team applies all the tips we’ve discussed so far, you’ll be confident all your Jira Software issues are current and have complete information. And you can see it all in the Release Hub – your one-stop shop for assessing the status of a release.

The Release Hub provides a roll-up of all the issues in each release version. With all of that information in one place, Jira Software can help you assess the health of your release and answer questions like “Has all the code in this version been reviewed?” or “Are there any open pull requests remaining in this version?” Anyone with access to the Release Hub can check out the status of work in progress. No need to build custom reports or hold extra status meetings.

Putting it all together

Jira Software and Bitbucket might never make your mouth water the way coffee and donuts do, but they stand stronger together nonetheless and help your team move faster.

If you’d like to see for yourself how Jira Software Server and Bitbucket Server work better together give Bitbucket Server or Data Center a try today.