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.
- By default, JIRA issue keys (aka Issue IDs) are of the format <project key>-<issue number>, eg. ABC-123.
- 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.
Project Key Pattern
Through the property
jira.projectkey.pattern, the administrator can specify a Perl5 regular expression defining the rule for a valid project key. During project creation, the user must specify a project key that conforms to this rule.This can be done by editing jira-application.properties. You will then need to restart JIRA (JIRA Standalone) or rebuild the JIRA webapp and redeploy in your app server
Default Project Key Pattern
By default, the JIRA project key configuration requires two or more uppercase alphabetical characters — based on the regular expression (
Configuring Different Project Key Patterns
To configure a different rule for your Project Key syntax, change the regular expression in the
<jira-install/atlassian-jira/WEB-INF/classes/jira-application.properties file. Below is a list of common examples and patterns:
Resulting Issue IDs
XXYY, where X indicates two fixed letters, Y represents two fixed digits
TQ09-01, TQ09-02, etc.
XZ+, where X indicates one fixed letter, Z+ presents one or more digit or alphabet
ACAT51-1, AAA5-1330, A20091-15
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.
Do not use "." and "-"
- Avoid using the dash (
-) character, as this character is inserted automatically after the regular expression and before the issue ID number.
- Avoid using the dash (
.) 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.
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
You can change
jira.projectkey.warning in the
jira-application.properties 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
jira-application.properties file also contains the following properties:
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)
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.