Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
Community Members
Community Events
Community Groups

Jira and Jira Align Integration: Release Vehicle/Fix Version Best Practices

Before integrating Jira with Jira Align, there are some best practices that should be considered. Some are a little more rigid than others; while others can lend themselves to some workarounds. Let's explore further to understand what these are, why these are important and the potential impacts. 


Caution of syncing release vehicles/fix versions

Fix versions in Jira are created by project and could potentially create duplicate release vehicles in Jira Align that represent the same release.

Why: When using 1 project to 1 board structure, each project has its own fix version that could be duplicated over projects. All of these fix versions will sync over to Jira Align as individual release vehicles.

Workaround: Grouping release vehicles in Jira Align is an option but will not solve this as all of the fix versions will still be created as individual release vehicles in Jira Align.


Assigning releases to features

If wanting to assign releases to features, release vehicles would need to be created in Jira Align and fix versions would need to be created in Jira. In turn, these should not be synced with each other and would need to be maintained manually.

Why: The recommendation is to not sync release vehicles in Jira Align and fix versions in Jira. Due to this, if there is a need/desire to track work by release, it would need to be maintained manually.


Integration behaviors to be aware of

If the Fixed Version sync between Jira and Jira Align is enabled in the Jira connector settings:

  • A release vehicle will be created for each project the fixed version has been assigned to even if it is the same name
  • In Jira Align, if different features from different programs (aka Jira projects) are added to the same release vehicle, it won't sync because you can't have 2 projects tied to the same release vehicle. It must be unique.


Related Articles


If I opt to no longer sync fixVersions, I would have to manually create Release Vehicles in Jira Align and assign these to Jira Align work items (Features, and possibly Stories and Defects).   That in and of itself is not a big deal.

But then, if I revise a fixVersion on a Jira issue, the Release Vehicle on the corresponding work item in Jira Align will not automatically update.  Likewise, if I update a Release Vehicle value on a Feature in Align, the corresponding Feature (Epic) in Jira will not update its fixVersion.  I would be forced to somehow manually reconcile the Release Vehicle values in Jira Align work items with the fixVersion values in the corresponding Jira issues.  And I would have to do this periodically.

How could I perform such a reconciliation and know at a glance which value -- the Release Vehicle in the Jira Align work item, or the fixVersion in the Jira issue -- should take precedence when they do not agree?  How could I generate a report without going through tedious exports?  How can I avoid spending lots of time pouring over Excel and manually editing the corresponding work items or issues to get them to agree?

What I've been doing is allowing fixVersion and Release Vehicle to sync.  I establish distinct Release values in each Jira project.  So instead of four team-level Jira projects (e.g. with keys TLA, TLB, TLC and TLD) each having one Release named 1.0.0, they would each have one Release named A 1.0.0, B 1.0.0, C 1.0.0 and D 1.0.0, respectively.  Likewise, the corresponding Features in the program-level project in Jira would have 4 releases such as PL A 1.0.0, PL B 1.0.0, PL C 1.0.0 and PL D 1.0.0.  This gives me a total of 8 distinct Releases (8 fixVersions) in Jira.  And once synced, I'd get 8 corresponding Release Vehicles in Jira Align -- all for a single 1.0.0 release (across a suite of products).  That's an awful lot of fixVersions and Release Vehicles to track...

An Aside:  I could refine my scheme a bit and create only 5 releases total by adding only a single Release value of 1.0.0 to the PL project.  But in my company, version 1.0.0 of product A may ship before 1.0.0 for product B, and so on - so separate Releases for the Epics/Features allow for distinct ship dates for the four products.

...But at least these 8 releases would have distinct names (so no duplicate Release Vehicles in Align).  And I do not have to worry about reconciling edits to fixVersion or Release Vehicle field values on individual issues and work items between Jira and Jira Align.  I suppose I can group the 8 related Release Vehicles on the Jira Align side to make this a little less incoherent.

But this is sheer nastiness.  There has got to be a better way to manage releases:  an enhancement to Jira Align so there would be an option to allow many releases in Jira to map to a single Release Vehicle in Jira Align.  Ideally, this mapping could be done automatically based on a user-specified Release format (e.g. a RegEx so the example 8 release values in Jira I mentioned earlier could be automatically mapped to a single new Release Vehicle called 1.0.0).  And any change to a work item's Release Vehicle value would sync back to the corresponding Jira issue, using the appropriate release format, e.g. setting a Story work item to Release vehicle 1.4.0 would sync to the corresponding Jira issue in the TLB project as fixVersion B 1.4.0, via the automatic mapping. 

Or perhaps something even simpler and easier.

By keeping fixVersion and Release Vehicle synced, I believe Jira Align can note the ship date for the Release value associated with each fixVersion it encounters, and use that to automatically assign Program Increment to a work item (I may be wrong about how this works, but I think there is something to it).  if I disable the sync, I lose that auto assignment and now have to manually maintain the Program Increment field in Jira Align work items as well.

This really scares me, I was thinking Jira Align would make Release tracking easier ....


Log in or Sign up to comment
Community showcase
Published in Jira Align

Rockin' the Roadmap - How to make most of the Roadmap with Jira Align

The roadmap challenge for large scale agile enterprises Regardless of the agile framework you use, the agile enterprise has a massive scale with the challenge to connect hundreds of teams and thous...

2,586 views 7 26
Read article

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you