Documentation for JIRA 5.1.x. Documentation for other versions of JIRA is available too.

JIRA provides the ability to specify the format of project keys within the system. This is achieved by defining a regular expression 'rule' that governs the valid project key format

(info) Please Note:

  • By default, JIRA issue keys (aka Issue IDs) are of the format <project key>-<issue number>, eg. ABC-123.
  • (warning) 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.

(warning) The information on this page does not apply to JIRA OnDemand.

Project Key Pattern

The jira.projectkey.pattern property allows JIRA administrators to specify a Perl5 regular expression value that defines the rule for a valid project key. During project creation, JIRA project administrators must specify a project key that conforms to this rule.

This property and its regular expression value can be defined through the Advanced Settings page.

Default Project Key Pattern

By default, the JIRA project key configuration requires two or more uppercase alphabetical characters — based on the regular expression ([A-Z][A-Z]+).

Configuring Different Project Key Patterns

To configure a different rule for your project key syntax, change the regular expression (via the 'Advanced Settings' page). Below is a list of common examples and patterns:

Pattern Requested

Expression needed

Resulting Issue IDs

Comments

XXYY, where X indicates two fixed letters, Y represents two fixed digits

([A-Z]{2}[0-9]{2})

TQ09-01, TQ09-02, etc.

[A-Z] Any character from A to Z
{2} Matches the preceding character 2 times exactly
[0-9] Any character (i.e.digit) from 0 to 9

XZ+, where X indicates one fixed letter, Z+ presents one or more digit or alphabet

([A-Z][A-Z0-9]+)

ACAT51-1, AAA5-1330, A20091-15

[A-Z] Any characters from A to Z
[A-Z0-9] Any character from A to Z or 0 to 9
+ specifies [A-Z0-9] as one or more characters from A to Z or 0 to 9

(info) Please Note:

  • JIRA prepends the regular expression specified with '^' and closes it with '$' for an exact matching rule within the system.
  • The project key must only be allowed to contain ASCII characters, as it is used in HTTP GET requests.
  • The project key only supports uppercase characters. For simplicity, use uppercase characters in your expressions as JIRA will convert any lowercase characters to uppercase ones.

(warning) Do not use ".", "-", or "_"

  • Avoid using the dot (.) character (i.e. dot/period/full-stop), as the CreateOrCommentHandler currently fails to add comments to existing issues if the project key contains a dot (.) — see JRA-23180.
  • Avoid using the dash (-) character, as this character is inserted automatically after the regular expression and before the issue ID number.
  • Avoid using the underscore (_) character as there is a current bug in JIRA 5.x that the activity streams will not work for project keys using underscores — see JRA-27967.

(minus) Warning!

  • If a number of issues have already been created in your JIRA installation, then changing the project key is not recommended.
  • If you must change the project key pattern after issues have already been created, use a regular expression that allows a more 'permissive' project key pattern than the current one (e.g. use a regular expression which will still be valid for existing project keys defined in your JIRA installation).

Customising the Error Message for Invalid Keys

If JIRA detects that the project key entered does not match the jira.projectkey.pattern, it will throw the error message defined in jira.projectkey.warning.

You can change jira.projectkey.warning in the jira-config.properties file so that when a user keys in the wrong format, they will be informed of the correct pattern to use.

Testing Your Regular Expression

A variety of tools allow searching using a Regular Expression. Most text editors will allow a Regular Expression search. There are also a variety of websites available to for testing a Regular Expression available from an Internet search.

Project Key Details

You can customise the following properties in the jira-config.properties file:

  • jira.projectkey.description — a configurable description (to match the project key pattern) displayed on project creation
  • jira.projectkey.warning — a configurable validation warning (to match the project key pattern)

(info) Please Note:

  • It is not possible to configure the issue key pattern as JIRA expects this key to conform to specific rules.
  • Further information on Perl5 is available here.



See our Getting Help page for details.



Raise an issue for our developers.



See answers from the community.



Tweet, blog and update our documentation.

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.