Documentation for JIRA 6.4. Not using this? See below:
(JIRA 6.3.x documentation | JIRA Cloud documentation | earlier versions of JIRA)

Skip to end of metadata
Go to start of metadata

About issue linking

Issue linking allows you to create an association between issues on either the same or different JIRA servers. For instance, an issue may duplicate another, or its resolution may depend on another's. New installations of JIRA come with four default types of links:

  • relates to / relates to
  • duplicates / is duplicated by
  • blocks / is blocked by
  • clones / is cloned by (this is used when issues are cloned)

Issue linking also allows you to:

  • Create an association between a JIRA issue and a Confluence page.
  • Link a JIRA issue to any other web page.

You can add, edit or delete link types to suit your organisation, as described below.

(info) Note:

  • Your users must have the Link Issues permission before they can link issues.
  • Issue linking must be enabled in order for your users to be able to link issues. Issue linking is enabled by default. If your organisation does not require the ability to link issues, you can disable it globally for all users as described below.


Adding a link type

To create a new link type, e.g. 'Causes':

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose > System. Select Issue Features > Issue Linking to open the Issue Linking page.
    (tick) Keyboard shortcut: g + g + start typing issue linking
  3. In the 'Add New Link Type' form at the end of the page:
    • Enter 'Causes' in the Name text field.
    • Enter 'causes' in the Outward Link Description text field.
    • Enter 'is caused by' in the Inward Link Description text field.
  4. Click the Add button.
  5. This returns to the Issue Linking page, with a new section listing the Causes link type.

Screenshot: the 'Issue Linking' administration page

Editing or deleting a link type

(info) It is recommended that you do not edit or delete the Clones link type, as this is used to automatically link issues when they are cloned.

To edit or delete a link type:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose > System. Select Issue Features > Issue Linking to open the Issue Linking page.
    (tick)Keyboard shortcut: g + g + start typing issue linking
  3. Locate the link type you wish to edit or delete, and click the link type's associated Edit/Delete link in the Operations column.


Configuring issue linking for external applications

It is possible to create links to issues on a remote JIRA site or pages on a Confluence site (running Confluence version 4.0 or later). To do this, create fully reciprocal application links between your JIRA site to the remote JIRA or Confluence site. Fully reciprocal application links mean that:

  • An application link must be configured on each server to the other.
  • Each of these application links must have both incoming and outgoing authentication configured to each other's servers.

To configure fully reciprocal application links between your JIRA site and a remote JIRA or Confluence site:

  1. Log in as a user with the JIRA System Administrators  global permission.
  2. Create an application link to your remote JIRA or Confluence site. (See Adding an Application Link  for details.) When creating the link:
    • During step 2 of the wizard, ensure you choose the option to create a link from the remote server back to your server.
    • During step 3 of the wizard, choose the These servers fully trust each other option. This will ensure that incoming and outgoing authentication is configured for the application link on each server to the other server.
  3. If you configured a fully reciprocal application links between your JIRA site and a Confluence site, ensure that the Confluence site's system administrator has enabled the Remote API (XML-RPC & SOAP) feature, since this Confluence feature is disabled by default. See Enabling the Remote API in the Confluence documentation for details.
    (warning)  If you do not enable this feature, JIRA will not be able to communicate with Confluence. As a result, your users:
    • Will see Failed to load messages in the Confluence Wiki page links they create on JIRA issues.
    • Will not be able to search for Confluence pages using the Find a Confluence page dialog box.

(warning) Please Note: You can create a one-way application link from your JIRA site to a remote JIRA site or Confluence site. However, some loss of functionality will be experienced by your users when they create remote links. For instance, if your users create a link to a remote JIRA issue, they will find that the Create reciprocal link check box on the Link dialog box will not function correctly. Hence, it is recommended that you create fully reciprocal links instead.

Disabling issue linking

To disable issue linking for your entire JIRA site, for all users:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose > System. Select Issue Features > Issue Linking to open the Issue Linking page.
    (tick)Keyboard shortcut: g + g + start typing issue linking
  3. A status message indicates whether issue linking is enabled. If issue linking is enabled, click the Deactivate button. The Issue Linking page reloads, stating that linking is disabled.


Configuring the order of linked issues displayed on the 'view issue' page

JIRA system administrators can define the order in which linked issues are displayed in the Issue Links section on the 'view issue' page. This is done by editing the value of the jira.view.issue.links.sort.order property on JIRA's Advanced Settings page.

Specify the fields by which to sort issues in the Issue Links section on the 'view issue' page by entering the appropriate 'value' for each field in a comma-separated list. This property behaves similarly to a list of values specified after the ORDER BY keyword in JIRA Query Language (JQL), whereby sorting is conducted by the first and then subsequent fields specified in the list.

The jira.view.issue.links.sort.order property can accept the following individual field values: 'key', 'type', 'status', 'priority' and 'resolution'.


  1. Anonymous

    Is it true that using "blocks" or "is blocked by" will do nothing to actually prevent a blocked issue from being resolved until the blocking issue is resolved?  That is, denoting a blocker this way is purely for informational purposes only?

    1. The JIRA Workflow Toolbox plugin from

      provides this functionality as a workflow Validator. You can specify a message to appear when the transition is attempted. It's not a free plugin, though.

  2. Anonymous

    I have a story in project A that has multiple links to issues in Project B and C. I would like for the time tracking from the issues from Project B and C to show under story A. Is there currently a way to do that? 

    1. Hi

      I have the same need indeed and I didn't find anyway to do this. It looks like the only level of estimation / remaining data aggregration is between epic & sub tasks. Anybody has any idea what is best to be done ?

  3. Is it possible to display Web Links in JIRA Search results with the 'Links' column? It appears that currently only JIRA Issue links are displayed in the Search results.

  4. It's good to see someone from Atlassian cleaning up (aka, DELETING) comments..  yet I'm disturbed by the fact the content she (Susan Griffin) has removed has not been incorporated into the main document above first.  That's poor style and disingenuous to the user community at large who basically had discussions to elaborate on the issue linking topic helping each other to figure out the poorly documented/integrated feature..  

    1. Hi Peter. I've been working with the Support team to improve page performance. Unfortunately, one of the things we've had to do in a few cases is to remove (a lot) of older comments. In one case, this improved page load performance by over 50%! I have tried to remove comments that were years out of date, I'm very sorry if I may have missed some relevant information. 

      1. Maybe the developers should work on the performance of comments then..  If 10 comments on a page slows the page down 50%, then they're not doing their jobs properly.

  5. Anonymous

    So i just want to make sure i understand this correctly; even though blocking links between issues are defined, no out-of-the-box validator is available to prevent transitions of tasks that are blocked by the linked task?  I find it a bit strange that links are offered, yet we have to purchase a third party component to actually make them useful.

    1. Yes you are correct..  Links are informational only, they provide 0 value in any workflow transactions as far as I know (without third party bits I can't use since mine's on OnDemand)

  6. Hi Everyone,

    Is there a ways through which the issues linked as "Duplicate" are automatically closed/resolved once any of the issues is closed/resolved.

    Please suggest on the same.

    1. Nope sorry..  links are mearly a form of documentation.. they don't/can't partake in any form of workflow initiating actions.

      1. Is there any 3rd party plugin that can be used for the same?

        Or any way we have script an addon?

        1. Not that I'm aware of, and very unlikely if you're on the ondemand version.

        2. Yes it seems like the plugin  mentioned above gives u ability to set conditions within a workflow by link type

  7. Can workflow depend on an issue type. Example if I have 2 issue types new and bug, and for each issue type different workflow. 

    also, Can the process inside the workflow itself depened on the issue type, example. If i have workflow like

    Open, collect data, process data, assign etc..

    process data can use only if issue type is New Data. other wise the flow will be

    Open, process data, assign etc.. 

    1. Can workflow depend on an issue type

      Yes it can, you must define it in your workflow scheme.


      Can the process inside the workflow itself depened on the issue type

      This is the same question as the first one but differently asked, The answer is "Yes it can, you must define it in your workflow scheme." 

  8. Is there a possibility to update a linked issue once the parent issue changes a status or resolution (or any other attribute for that matter)?

    1. I have this same question. I've been looking for an answer.

  9. Hi,

    I am currently on JIRA version 6.1. I am trying to set up a workflow that only allows any issue from transiting to "Closed" and staying in that "Closed" state only when all issues blocking it are "Closed". 

    While trying to set up a custom workflow, I managed to:

    • Disable the ability of Issue A, being blocked by Issue B, from entering the "Closed" state. (using JIRA Workflow Toolbox plugin)
    • Transit the state from "Closed" to another appropriate state when Issue B transits out of the "Closed" state.
    • Disable the ability of adding a link to Issue A when it is closed (using

    However, when opening up any issue to create a link, I can still search and apply the link "Blocks" to Issue A, effectively bypassing the I set up. Is there any way for me to ensure that links with "Blocks" are not created to a closed issue?

  10. How do I link an issue to project versions?

  11. I've seen the instruccions for disabling issue linking for the entire JIRA site but... can i disable issue linking for only some confluence pages? How could i do this?

    I mean, i'd like to have some confluence pages where i can add some links to tasks without showing these links in the JIRA task.

    Thanks in advance!


    1. I haven't seen that in JIRA, where you can have links to an issue but not links from an issue. The code underneath it would support it though I think

  12. Missing Information:

    What happens to the links for existing issues when a link type is deleted?