JIRA is now available as three separate applications, JIRA Software, JIRA Service Desk, and JIRA Core. For more information on administering these applications, refer to the Administering JIRA Applications documentation.

Configuring Issue Linking

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'.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

24 Archived comments

  1. User avatar


    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?

    09 Aug 2012
    1. User avatar

      Phil Lancaster

      The JIRA Workflow Toolbox plugin from https://marketplace.atlassian.com/plugins/com.fca.jira.plugins.workflowToolbox.workflow-toolbox

      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.

      01 May 2013
  2. User avatar


    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? 

    01 Feb 2013
    1. User avatar

      Julien Fritsch


      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 ?

      23 Dec 2013
  3. User avatar

    Jeff Kaffenberger

    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.

    02 Apr 2013
  4. User avatar

    Peter Drier

    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..  

    03 May 2013
    1. User avatar

      Susan Griffin [Atlassian]

      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. 

      05 May 2013
      1. User avatar

        Peter Drier

        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.

        10 May 2013
  5. User avatar


    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.

    19 Jun 2013
    1. User avatar

      Peter Drier

      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)

      19 Jun 2013
  6. User avatar

    Vaibhav Gupta

    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.

    24 Sep 2013
    1. User avatar

      Peter Drier

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

      24 Sep 2013
      1. User avatar

        Vaibhav Gupta

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

        Or any way we have script an addon?

        26 Sep 2013
        1. User avatar

          Peter Drier

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

          01 Oct 2013
        1. User avatar

          Alex Tabrizi

          Yes it seems like the plugin https://marketplace.atlassian.com/plugins/com.fca.jira.plugins.workflowToolbox.workflow-toolbox  mentioned above gives u ability to set conditions within a workflow by link type

          16 Oct 2014
  7. User avatar

    ayman salah

    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.. 

    06 Nov 2013
    1. User avatar

      Alex Tabrizi

      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." 

      16 Oct 2014
  8. User avatar

    Eimantas Vaiciunas

    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)?

    19 Nov 2013
    1. User avatar

      Robert Roskam

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

      20 Jan 2014
  9. User avatar

    Stephen Chai


    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 jira.permission.link.group.1=AN_EMPTY_GROUP)

    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 jira.permission.link I set up. Is there any way for me to ensure that links with "Blocks" are not created to a closed issue?

    01 Dec 2013
  10. User avatar

    Sujay Ghosh

    How do I link an issue to project versions?

    15 Jan 2014
  11. User avatar

    juan manuel garrido

    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!


    11 Feb 2014
    1. User avatar

      Matt Doar [ServiceRocket]

      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

      11 Feb 2014
  12. User avatar

    James Rickards

    Missing Information:

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

    03 Dec 2014
Powered by Confluence and Scroll Viewport