Editing a project key
Before you begin
Your desired project key must conform to the project key format restrictions specified in your Jira applications. By default, the project key format must be at least 2 characters long and contain only uppercase letters.You can change the project key format to enforce different restrictions. See Changing the project key format for instructions.
- Perform this change during a low usage period — Jira applications will start a background re-index when you save your updated project key. This can have a performance impact on your instance. Note, you cannot choose a 'Lock Jira and rebuild index'. The background index will be faster anyway, as it is limited to issues for the project.
- Communicate changes to your users — Ensure that you are aware of the consequences of changing the project key, and have adequately prepared your users for the changes. See the Changes section below.
Editing the project key
- In the upper-right corner of the screen, select Administration
> Projects. - Select the project that you'd like to change.
- Select Edit in the Actions column of the project you want to change.
- Edit the project key, and click Save details. Only project types for applications you have installed will be available.
This will start a project re-index, which you need to acknowledge when it finishes.
Note:
- If you update any other project detail fields, you'll see the changes immediately. You won't need to wait for the re-index to finish.
- If you cancel the background re-index, you will have trouble searching for issues related to the project. If you do need to cancel it, you can run it again later to fix these problems.
Post-update tasks
- Fix the project entity links — When you connected Jira to another Atlassian application, entity links would have been automatically created between your Jira projects and the relevant "projects" in other applications, e.g. Confluence spaces. If you change the key of a Jira project, you will need to fix the project entity links, as described in Creating links between projects.
- Updating Jira Software agile board filters - If your Jira Software agile boards use the old project key, the board filters may need to be updated to reflect the new project key. Otherwise the board might not display issues from the renamed project.
Notes for change management
While editing the project key is a major change, in most cases, your Jira project will work as you'd expect with a new key. There are a few cases that you should be aware of, which are listed below. We recommend reviewing these and advising your users accordingly.
- The old project key can be used in JQL queries — Users won't have to update issue filters that reference the old project key.
- If you use Confluence with Jira, the Jira issue macros in Confluence will continue to work. Please note, if you don't see the change straight away, allow some time for the cache to refresh.
- You won't be able to create a new project with the old project key. However, you can change the renamed project back to the old project key. If you delete the project, all associated keys will be freed and you'll be able to re-use them.
- Links will work, whether they are inside Jira or from external sources. However, link aliases will not be updated — For example, if you have a link to an issue 'EXAMPLE-1' in the description of an issue, and you change the project key 'EXAMPLE' to 'DEMO', then the alias 'EXAMPLE-1' will not be updated to 'DEMO-1'. The link will still direct you to DEMO-1 though.
- If you are using a gadget with a global filter, you will need to update the filter after the project is renamed.
- All attachments will be accessible after the project key change. Please note, however, that the directory that they are stored in (under the
<Jira Home>\data\attachmentsdirectory) will retain the old project key. For example, if you change a project's key from TEST to DEMO, the attachments will be stored under<Jira Home>\data\attachments\TEST. If you export a renamed project, and then import it, it will have the updated project key, i.e. the original project key will not be retained. In fact, all historical keys for that project will be removed. There is a workaround for this that involves changing data directly in your database, see this Answers post.
Related topics
Changing the maximum project key length — You can change the maximum characters allowed for a project key. Navigate to the General Configuration page of the Jira administration console, as described on Configuring Jira application options, and change the Maximum project key size field. Changing the project key format — You can change the format of a project key. This restricts the format of a project key when it is created or edited (as described above). For instructions, see Changing the project key format.
Notes for developers
- REST API calls will still work with old project key — REST calls that specify an issue key will work with the old issue key after the project key has changed. For example,
/rest/api/issue/EXAMPLE-100will still work after the project key is changed fromEXAMPLEtoDEMO. - We have created a new event, ProjectUpdatedEvent. This event is triggered any time a project's details are changed, including changing the project key.
- If you need to retrieve all issue keys and project keys (historical and current), you can do this via the following:
- REST:
- Get all project keys for a project:
/rest/api/2/project/<project key>?expand=projectKeys
- Get all project keys for a project:
- Java API:
- Get all project keys:
com.atlassian.jira.project.ProjectManager#getAllProjectKeys - Get all issue keys for an issue:
com.atlassian.jira.issue.IssueManager#getAllIssueKeys
- Get all project keys:
- REST: