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.

Before you begin

  • Your desired project key must confirm 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

  1. Navigate to the desired project, 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 update any other Edit Project 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\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 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-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 issuecom.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