JIRA - End of support for project key format configuration in JIRA 6.0!

Mirek Community Champion Nov 22, 2012

Hi all,

I noticed a announcement from Atlassian that:

From JIRA 6.0, due in the first half of 2013, JIRA will no longer support project key format configuration.

Roy Krishna said:

Changing the project key will be 'allowed' but not supported and customers can still change the project key format the way they have always done.

Not supported means that if things break in JIRA because customers are using non supported characters then those issues will not be fixed.

More info: https://confluence.atlassian.com/display/JIRA/End+of+Support+Announcements+for+JIRA

Is this a good decision? What will this mean for end users? What will happen with current project that use different key format and already have issues?

My comment below:


6 answers

1 accepted

7 votes
Accepted answer

It's a bad decision in its current format.

I would completely understand a decision to stop supporting project keys with "odd" characaters in them, but unless full support for alphanumeric keys is implemented, this is going to stop people using Jira. Numerics are a critical part of some projects codes because people embed information in them.

I work mostly in London. Can you imagine how many projects I've seen with some variation of "Olympics 2012" in them? What about 2016? How do people differentiate between 2012 and 2016. I know the BBC use Jira, and have projects like BBC1xxx, BBC2xxx. They need the numbers. It's immensely useful for many people to have the option of a separator as well - ABC123XYZ is less readable than ABC_123_XYZ

Not too thrilled about it either. 1D/2D/3D visualisation or calculation software kind of lose their meaning or even distinguishing keys when dropping numbers from their trackers.

Mirek Community Champion Nov 24, 2012

Exacly! This is the thing that I am also affraid.. I am also having a lot of projects that use numbers in the keys.. It is a lot easier! I understand that we should not use "_", "." or "-" in the key, but at least numbers should be allowed..

Agree, the use cases for alpha numeric project keys are huge, eg when projects relate to product codes, lets say the "DP600". My first project key for that ended up being "DPSIXOHOH". After updating project key to support ONLY alphanumeric, DP600 was the natural project key. Having some kind of separator character seems a natural extension too. I can understand Atlassian wanting to reign in what project keys can be but they will be shooting themselves in the foot by not supporting basic alphanumeric project keys.

4 votes
Mirek Community Champion Nov 25, 2012

How I see every change to the project keys..

We are using JIRA in our company since JIRA 3 ..When starting creating projects everything was ok.. You were able to change the regular expression and projects could use numbers "_", "," or "." (every character!)


When moving to JIRA 4.0 then information appears to only avoid dash character

Avoid using the dash (-) character,


In JIRA 4.2 next information that was including also another character..

Do not use "." and "-"


JIRA 4.3 and another new information..

If you use GreenHopper or have integrated JIRA with Bamboo, you should avoid changing JIRA's default project key format as both GreenHopper and Bamboo only support this key format.


JIRA 5.1 and we also see another change..

Do not use ".", "-", or "_"

Now in JIRA 6.0 it sounds like we will be not able even to configure the key because it was causing a lot of problems..

We are ending support for project key format configuration, as changing the product key format will break JIRA plugins, integration with other Atlassian products, as well as core JIRA functionality.

End of support means that Atlassian will not fix bugs related to project key configuration past the support end date.

Is this how it should be done?

We have projects (a lot!) that were created in JIRA 3.x, 4.x when there was no problem either with GreenHopper other Bamboo.. when have used also "_" characters and numbers..

What we suppose to do now when more than 60% of our projects were created in the past and now are not working properly for example due to Activity Stream issue:


How I can change project key in my production projects (about 1000) that already use "_", numbers or other characters if in the latest documentation I see message like this:

The changing of project keys is not covered by Atlassian Support and is considered to be risky as this involved manually manipulating raw .xml data.


If something will go wrong a lot of people can be affected..

For me GreenHopper, Bamboo, Activity Streams and other this that was having problems with specific characters should be fixed and then when all old project are working fine consider disallowing changes in the project keys.. or at least please give us an option to easily change the project key of a project..

However on the other hand in past few years for example there is already a lot of links that point to specific issues.. in customer documentation, presentations, reports, filters, issue creation links.. changing now the project key could break everything.

The problem still exist and I think it will not be quickly fixed by making that kind of step.. There will be even more problems if user will be not able to include numbers in the keys..

Thanks for going back over the docs to clarify it - I was working from memory!

I first ran into this when someone wanted to use a - in a Jira 3.something project (Not sure of the exact version, but it was between 3.0.3 and 3.3.1). Jira coped with it ok, but a couple of the plugins were assuming that the "-" was the separater between project key and the issue number, so they fell over quite spectacularly. I've never even tried to use a - in a project key since. Also, given that many punctuation characters mean different things in places (. in regex, ? in urls, etc), I've stayed well away from them too.

I remember a while ago, Atlassian were blogging about their core principles, one of which was DFTC (bad words involved in that acronym). I'm afraid failing to support configurable keys to some extent, breaks that principle, as many of their customers need long alphanumeric keys with a separator.

Mirek Community Champion Nov 27, 2012

I am just trying to understand what will happen after releasing JIRA 6.0..

If we will upgrade to this version and there will be an end of support for custom project keys then what next? .. we are left alone with those all old issues that were not fixed yet?

For example as I mentioned currently we are having an issue with the Activity Streams because we used in the past underscores in project keys (we do no use it anymore for new project after JIRA 5.x).. If we will have another issue in JIRA 6.0 related to the same projects that are using underscore in project key then it will not be supported? Do I understand this correctly?

I do not want to see in the future a message from support that: "This issue is caused by custom project key.. We are not supporting this activity...".

What option do we have? Change the project key? Start a new clean instance and close all affected projects? If we see a warning like this:


  • If a number of issues have already been created in your JIRA installation, then changing the project key is not recommended.


then I think we should not change project keys because we have a lot affected projects with a lot of issues.

If Atlassian developers will fix all issues related to the project keys in JIRA 6.0 and future releases then I am fine with using default project key in the future (even without numbers), but if we are facing already few issues and those issues will be not fixed for all current project that have custom project key and are still heavily used (even from JIRA 3.x) then I think it is not how it supposed to be done..

1 vote
Mirek Community Champion Mar 17, 2013

Some good news from Atlassian:

Update 15 March 2013

Based on customers feedback, we are investigating re-introducing support for project keys with different configurations than just letters, specifically looking at numbers and potentially underscores as well and the impact they have on Atlassian and third party plugins. For now, we advise customers not to change their project keys away from their current format. We'll have an update before JIRA 6.0 ships.

Related documentation:


I like it!

I read the notice and I am even not sure what it means? They should restate what the 'standard' project key definition is. Yes, I know we can currently define a regular expression, but somehow they should be supporting internationalization. I need more information to understand the full ramifications.

The "standard" for version 2 and 3 was a key of 2 or more letters, with an upper limit high enough that you don't really care (I don't know what it was, but I never hit it)

In version 5, they chopped the maximum to 10 characters, which is too short.

In version 6, it looks like we won't be able to deviate from 2-10 letters, which is simply useless.

Thank you Nic for illuminating my point. We do not know what it means.

It also seems like the character limit will be configurable in 6.0 base upon the issue below, but qe will not not know until 6.X comes out.


Yup. I've seen it documented several times, but it was always quite well buried (in an appropriate and relevant place, but you always had to dig to find it), and never highlighted as a "standard", just the off-the-shelf default. I was highlighting the point that even if you could consider it a standard, it's one that has changed...

The changes in this case do not really seem to have been thought out fully.

I hope that they will propose an migration tool for that. Otherwisae, it will be impossible for us to upgrade.

Using the regexp on the xml backup file makes me fear...

Quite a lot of people are going to find it impossible to upgrade at all, they need flexible keys.

One of my clients cannot upgrade to 5.2 because of the project key length restriction. If this is not changed, they will need to move to another issue tracker and they are not happy about this since they invested time and money into the Altassian product suite.

There is no need for any character restriction if you think about it and create some API's to be used.

There are many potential solutions to this problem and now we just need to wait and see what happens.

0 votes
Mirek Community Champion May 19, 2013

Hi All,

Good news! Key update done by Atlassian in this case:

From JIRA 6.1, due in the second half of 2013, we will only support customised project keys that meet both of the conditions specified below:

  • The first character is a letter
  • Only letters, numbers or the underscore character is used

Examples of supported keys: PRODUCT_2013; R2D2; MY_EXAMPLE_PROJECT.
Examples of unsupported keys: 2013PROJECT (first character is not a letter); PRODUCT-2012 (hyphens are not supported).


Please note that our previous announcement for the end of project key format configuration in JIRA 6.0 no longer applies. This is largely due to the great feedback provided by you, our customers.

More info here

I am personally very happy that this announcement changed. Now 99% of our projects fit into new requirements!

Thank you very much Atlassian for reading our biggest problems and reacting on them!

Big thanks also to all of you for good discussion!

Best Regards,


PS. Let's hope that this will not change once again in JIRA 6.2 ;)

Excellent, that covers almost every scenario I was worried about.

Suggest an answer

Log in or Sign up to answer
Community showcase
Published Nov 27, 2018 in Portfolio for Jira

Introducing a new planning experience in Portfolio for Jira (Server/DC)

In the past, Portfolio for Jira required a high degree of detail–foresight that was unrealistic for many businesses to   have–in   order to produce a reliable long-term roadmap. We're tur...

2,912 views 19 22
Read article

Atlassian User Groups

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

Find a group

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

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you