Editing a Project Key

Editing a project key is not a trivial task. You should choose key that will suit your long-term needs when creating a project, rather than rely on editing the project key after the project is created. However, there are situations where you need to change the key for an existing project, e.g. change of product name.

The instructions on this page show you how to change the project key and describe the implications of such a change. If you are a plugin developer, you should also read the developer notes below.

Before you begin

  • Your desired project key must confirm to the project key format restrictions specified in JIRA. By default, the project key format must be at least 2 characters long and contain only uppercase letters.

  • Perform this change during a low usage period — JIRA 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

  1. Navigate to the desired project in JIRA, and access the project administration screen. Choose Project Administration (bottom of the project navigation sidebar) if you're on the Project summary screen.
  2. Choose the Edit Project button.
  3. Choose edit key next to the Key field.
  4. Update the key and choose Update.

Note:

  • If you updated other fields on the 'Edit Project' page as well, you will see the changes after you save your changes. You won't need to wait for the re-index to finish.
  • Don't cancel the background re-index. If you cancel it, then you will have problems 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 on Creating links between projects.

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 the Activity Stream 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\attachments directory) will be 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, 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 Options, and change the Maximum project key size field.

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-100 will still work after the project key is changed from EXAMPLE to DEMO.
  • 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
    • 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

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport