Documentation for JIRA 6.4 (This documentation includes the project navigation sidebar). Not using this? See below:
(JIRA 6.4 without sidebar documentation | JIRA 6.3.x documentation | JIRA Cloud documentation | earlier versions of JIRA)

Skip to end of metadata
Go to start of metadata

Issue linking allows you to create an association between two existing issues on either the same or different JIRA servers. For example:

  • An issue may relate to another.
  • An issue may duplicate another.
  • An issue may block another.

(Your JIRA administrator can customize the types of links that you can create.)

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.

On this page:

Issue links within an issue look like this:

Screenshot: the 'Issue Links' section within an issue

Note: Resolved issues (i.e. issues with a Resolution set) are displayed in strike-through font, e.g. DEMO-1.

To create links on JIRA issues, you need to have the Link Issues permission in the project(s) to which the issues belong.

Creating a link to another issue on the same JIRA site

To create a link to another issue on the same JIRA site:

  1. Open the issue you wish to link to another issue in the same JIRA site.
  2. Select More > Link to display the Link dialog box.
    (tick) Keyboard Shortcut: '.' + start typing link
  3. Ensure that the JIRA Issue item is selected at the left of the dialog box and then choose the type of link to be created from the This issue dropdown list.
    (info) If your JIRA system administrator has configured fully reciprocal application links between your JIRA site and another one, a Server dropdown list may appear above the This issue list. If this is the case, ensure your JIRA site appears or has been selected from the Server list.
  4. In the Issues field, specify the issue(s) to be linked to your currently viewed/selected issue. There are two ways to do this:
    • Type the full issue key (e.g. ABC-123) — or to link to multiple issues, press the 'Enter' key between each typed issue key.
      (info) If you have previously browsed an issue, you can quickly find the issue by typing the first few letters of the issue key (or part of the Summary), which will appear in an 'autocomplete' drop-down list for selection:
      OR:
    • Click the search for an issue link to use the Find JIRA issues popup, which allows you to perform either a simple text search or an advanced search for issues.
  5. Optional: Add a Comment to describe why you are linking these issues.
  6. Click the Link button at the bottom of the dialog.

Creating a link to an issue on another JIRA site

(warning) To create this type of link, your JIRA system administrator should have configured fully reciprocal application links between your JIRA site and the other JIRA site containing the issue(s) you want to link to.

To create a link to an issue on another JIRA site:

  1. Open the issue you wish to link to another issue.
  2. Select More > Link to display the Link dialog box.
    (tick)
    Keyboard Shortcut: '.' + start typing link
  3. Ensure that the JIRA Issue item is selected at the left of the dialog box.
    (info) Note:
    • This option will not be available if your JIRA system administrator has not configured an application link between your JIRA site and the remote JIRA site.
    • If, after selecting this option, you are prompted for authorisation, you may be required to log in to the remote JIRA site, which will allow your JIRA site to access the remote JIRA site on behalf of your account on the remote JIRA site.
      (info) This behavior means the application links configured between your JIRA site and the remote JIRA site use OAuth authentication.
  4. If your JIRA site is connected to multiple remote JIRA sites, choose the relevant JIRA site from the Server dropdown list.
  5. Choose the type of link to be created from the This issue dropdown list.
  6. Type the Issue key of the issue on the remote JIRA site that you want to link to. Alternatively, you can search for issues on the remote JIRA site by clicking the search for an issue link, which opens the Find JIRA issues popup.
    (info) You can link to any issue on the remote JIRA site to which you have access on that site.
  7. Select the Create reciprocal link check box to create the complementary link on the remote issue you are linking to, back to your issue. For example, if you create a blocks link type to a remote issue, the reciprocal link generated on the remote issue will be a is blocked by link type back to your local issue.
  8. Optional: Add a Comment to describe why you are linking these issues.
  9. Click the Link button at the bottom of the dialog.

Troubleshooting

(error) Problem: If you selected the Create reciprocal link check box but after clicking the Link button, discover that a reciprocal link from the remote JIRA issue back to your JIRA issue has not been created, then your JIRA system administrator has most likely created only a one-way link from your JIRA site to the remote JIRA site.

(tick) Solution: Ask your JIRA system administrator to configure fully reciprocal application links between your JIRA site and the remote JIRA site.

(error) Problem: If you attempted to create a reciprocal link but received the following message:

'A reciprocal link from issue 'XYZ-123' back to this issue was not created as the remote JIRA server returned the following error: No Link Issue Permission for issue 'XYZ-123'.' (where 'XYZ-123' is the issue key on the remote JIRA site),

then a reciprocal link on the remote JIRA site will not have been created, because the user account through which you authenticated on the remote JIRA site (at step 3 above) does not have the Link Issues project permission.

(tick) Solution:

  • Ask the JIRA project administrator(s) on the remote JIRA site to grant your user account the Link Issues project permission for the relevant project(s) to which you need to create issue links.
  • Alternatively, if the application link between your JIRA site and the remote JIRA site use OAuth authentication and you suspect you may have authenticated on the remote site with another user account that does not have the Link Issues project permission, repeat the procedure above but during the authorisation step (at step 3), authenticate on the remote site with a user account which has this permission.
    (info) If you are not prompted for authentication during authorisation, try clearing your browser's cookies first and repeat the procedure again.

Creating a link to a Confluence page

This feature is only supported in Confluence versions 4.0 or later.

(warning) To create this type of link, your JIRA system administrator needs to have configured an application link between your JIRA site and the Confluence site containing the pages you want to link to. 

To create a link to a Confluence page:

  1. Open the issue you wish to link to another issue.
  2. Select More > Link to display the Link dialog box.
    (tick) Keyboard Shortcut: '.' + start typing link
  3. Click the Confluence Page option at the left of the dialog box.
    (info) This option is not available if your JIRA system administrator has not configured an application link () between your JIRA site and the Confluence site.
  4. If more than one application link has been configured between your JIRA site and other Confluence sites, then choose the appropriate Confluence site from the Server dropdown list.
  5. Specify the Confluence page to be linked to your currently viewed issue. There are two ways to do this:
    • In the Page URL field, enter the URL of a page on the Confluence site you want to link to. For example:

    • Click the search for a page link. The Link dialog box is replaced by the Find a Confluence page dialog box.
      (info) If you are prompted for authorisation, you may be required to log in to the Confluence site, which will allow your JIRA site to access the Confluence site on behalf of your account on the Confluence site.
      This behavior means the application links configured between your JIRA site and the remote Confluence site use OAuth authentication.
      1. In the first Search field, specify one or more search terms that appear in the page you want to link to. This field is mandatory.
      2. Optional: In the second Search field, select the Confluence space to further narrow down the search.
      3. Click the Search button and then the title of the page you want to link to.
  6. Optional: Add a Comment to describe why you are linking these issues.
  7. Click the Link button at the bottom of the dialog.

Troubleshooting

(error) Problem: If Confluence page links you create show Failed to load on the JIRA issue or if you attempted to search for a Confluence page but received the following message:

'Content on the Confluence site could not be accessed because the Confluence server's 'Remote API' feature is disabled. The Confluence system administrator must enable this 'Remote API' feature for JIRA to successfully access this content.'

then JIRA was unable to communicate with the Confluence server to either:

  • retrieve information about the link or
  • conduct a Confluence page search in the Find a Confluence page dialog box.

(tick) Solution:

Ask the Confluence system administrator to enable 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.

Creating a link to any web page URL

To create a link to any web page URL:

  1. Open the issue you wish to link to another issue.
  2. Select More > Link to display the Link dialog box.
    (tick) Keyboard Shortcut: '.' + start typing link
  3. Click the Web Link option at the left of the dialog box.
  4. Specify the URL of the web page you want to link to.
  5. Specify the Link Text that will appear in the Issue Links section of the 'view issue' page and will be hyperlinked to your URL.
  6. Optional: Add a Comment to describe why you are linking these issues.
  7. Click the Link button at the bottom of the dialog.

To delete a link:

  1. Go to an issue that contains links, and locate the Issue Links section (see screenshot above).
  2. Hover your mouse over the link you wish to delete, and click the Delete (trashcan) icon that appears.

Searching for linked issues

You can search for issues that are linked to a particular issue. For details, please see the documentation on Advanced Searching.

(info) Be aware that this functionality does not extend to issues on a remote JIRA server.

48 Comments

  1. Anonymous

    Hello,

    Does JIRA have possibility to change issue linking on action screens?

    Thank you

    1. Anonymous

      Hello,

       

      I have de same question, you have results? Its possible do this?

      I need do this in a project... but i dont found in the post-functions a action that possibility realize this operation...

      If this is  possible... notify here...

      Thanks...

  2. Anonymous

    Where do the link comments appear?  I used to find them under (at least) the "all" tab, but now I cannot find them anywhere, even comments that were entered long ago.

  3. Anonymous

    Hi,

    Can we create task heirachy in jira? E.g. Task1 <End to Start> Task2 ...and so on. Also, same can be viewed in Gantt chart kind of view.

     

    Regards

  4. Hello,

     

    Is it possible to display the Linking Issues information in a search result?

    I'd like to see quickly if there is at least a link and if the remote issue is corrected.

     

    Thanks a lot.

    Regards,

    Fred

     

    1. Anonymous

      Yes, with the Links Hierarchy add-on and JIRA 6+. Look please at the picture below.

  5. Anonymous

    Hello,

    I have found that issues which are reopened (resolution also changed to reopen) are also shown in strike through font. Am I missing something?

    Regards

    1. Hi,

      I have the same problem. My understanding is that any value other than unresolved will case the strike through font. Depending on your workflow you'll have to set the resolution field to unresolved.

  6. Anonymous

    Is there a way to set that until the blocking issue has not been solved, the issue can not be resolved?t

  7. Anonymous

    What if I don't want to allow that it's possible to delete linking? Now it's forbidden to delete issues in permissions, but it doesn't prevent this transaction..

  8. Anonymous

    Same question as asked previously (anonyme - June 04) : how can I prevent user to do a task till another has not yet been done ?

    Tried with "is blocked by" link, but I was able to do whatever I wanted on the issue...

    Thanks

  9. Anonymous

    Can we link an issue while creating a new issue in the Create Issue page itself, instead of linking it through the 'More Actions -> Link Issues' option.

    Both the Issues are in JIRA only.

    1. Hi there,

      Yes you can do this, although only to other issues in the same JIRA installation (i.e. not to issues on another JIRA site).

      To do this, ensure that the screen used for your Create Issue issue operation (i.e. the Default Screen in default JIRA installations) has the Linked Issues field.

      Hence, on a default JIRA installation, all you should need to do is the Linked Issues field to the Default Screen. See Adding a field to a screen for details on how to do this.

      To link to issues on another JIRA site, you'll need to use the procedure above.

      Hope this information helps.

      Cheers,

      Giles.

  10. Anonymous

    Is there anyway to link a JIRA issue directly to an attachment on a Confluence page?  I would like to reference a requirements doc that I have attached to a Documentation page in my Confluence space.  If I can only link an issue to a page, then the user viewing the issue will have to figure out which of the many attachments he needs to view.  Thanks!

     

    1. Hi,

      Try this:

      1. In Confluence, go to the page with the attachment.
      2. Click Tools menu > Attachments
      3. Locate the desired attachment in the list.
      4. Right-click the attachment link and copy the link location.
      5. Paste the link in your JIRA issue.

      Kind Regards,
      Andrew

       

  11. I would like to change the fields that show in the "Issue Links" section when browsing an issue.  Currently only the icon for issue type, key, issue summary, icon for issue priority and icon for issue status is displayed.  I would like to add fields such as Assignee and a few custom fields.  What resource should I read in order to determine how to do this?

    Thanks for any help provided.

  12. Hi, we are using the advanced search in the  "Find JIRA issues" dialogue to link an issue with others. When typing in an JQL expression like "project = myProject" the resultlist only shows me 10 issues, but there are 124 Issues in this project. How can i display the exact search result here?

    Thanks for your help!

    Regards,
    Norbert

  13. Hello,

    Linking issue is a great feature but is there no way to have a hierarchical view of issues with their links. I know there is an old plugin but that we cannot use on JIRA on deman.

    The request would be to have a map of issues with their links and being able to have an overview of wich issues are linked together + possible to click on the link to go to the detailed view of the issue.

    1. Anonymous

      The Links Hierarchy provides a full hierarchical view of issues with their links on several locations (issue tab, issue navigator, Agile, etc.)

  14. When searching for issues the results can display also a column related to  Linked IssuesHowever that column always shows other JIRA issues - not web links.

    Is it possible to configure JIRA so that the Linked issues column in a search results screen can show (all of the) external web links if there are any? This would help in cases where external web links are used to point related issues existing on other (non-JIRA) bugtrackers. 

  15. Echoing Bryan's comment above, is there a way to edit the columns shown on issue view for the issue linking?  We'd really like to add assignee to these columns.

  16. Is it possible to configure the link JIRA issue screen to create a new issue (as well as search for existing issues)?

    I'd like developers who are working on a DEV issue to be able to more easily/quickly create a new DOC issue so that their changes can be documented – if they have to go through extra steps to create a linked DOC issue, the chances are they will forget to do it.

    1. Hi David,

      You can create a new issue in JIRA using the JIRA Issue macro. This page has more information:  Inserting JIRA Issues 

      Hope this helps!

      Denise.

      1. Thanks Denise that is useful from a Confluence perspective - but what I really want is for someone working on a JIRA issue in one project to be able to create a new JIRA issue in another project – e.g. a developer is working on or finishes their development issue, realises that a documentation issue needs to be created for it and can create a new doc issue and link it to it in one easy step... meaning, not having to go into the documentation JIRA project create a new issue there make a note of the JIRA number and then go back into the development issue and manually create the link.

        No offence to developers, but when it comes to documentation, they are typically (but not always) lazy - or it's something that they just forget about. LOL

         

         

         

         

        1. Hey David,

          Can you please raise a support request in our Support Portal in the JIRA Project, then we can help you out further. (smile)

  17. Anonymous

    Does anyone know if you are able to link an issue to a release?

    We would use this to include tasks/bugs that are fixed by a release to track them

  18. Hi,

    is it possible to always show all issue links in a Ticket?

    regards

    1. Anonymous

      Yes, if you install the Links Hierarchy add-on

  19. Anonymous

    Is it possible to select " linked issue " list ?

    I'd like to get issues whichis related another issue.

     

     

  20. Anonymous

    Hello!

    Is there search criteria that I can use which will show me all issues linked to a particular issue ID?

    I've been looking in the JQL docs, and all I'm seeing is the "Epic Link", which works really well for Stories linked to Epics, but not for other issue types linked to stories.

    Thanks!

  21. DIM

    A related question on filtering issues based on web links and see this info in issues view here: https://answers.atlassian.com/questions/172263/how-to-filter-and-export-issues-in-jira-based-on-web-links-information

  22. Anonymous

    I have some 50 issues in JIRA which I need to link to a single story. Is it possible to do? Currently I am doing one by one. It will be good if I can do it once.

  23. Anonymous

    I have some 50 issues in JIRA which I need to link to a single story. Is it possible to do? Currently I am doing one by one. It will be good if I can do it once.

    1. Hi Anonymous,

      1. Run your query for the issues that you want to link to "Main Issue".  Either:
        1. Copy the list and paste it into Excel OR
        2. Export the list into Excel
      2. In Excel, copy the key column (without the header) to capture all of your issues key.
      3. Go to the Main Issue that you want your List 50 to link to
      4. Open the Link Dialogue as were you when linking 1 by 1
      5. Paste all of the copied keys from Excel.
      6. Click anywhere outside of the Link field.  (Do not hit "Enter" on your keyboard; that will only select the first key populated in the drop down field).

      That's the only way I'm able to link in bulk.

      Hope that helps.

  24. How do you query the "Link Text" and "URL" fields?  I've tried "Task Type" = ABC and parent = XYZ and "URL" ~ "123" and "Task Type" = ABC and parent = XYZ and "Link Text" ~ "123", but get "Field 'Link Text' does not exist or you do not have permission to view it."  Those fields are not listed in the "Issues Features" > "Issue Linking" administration page.

  25. Hi!
    In the Deleting a Link section, I suggest to complete the following sentence with the information of where such trashcan icon will appear:

    Hover your mouse over the link you wish to delete, and click the Delete (trashcan) icon that appears at the far right of the linked issue

    I have a couple of users that did not notice such icon as it was at the far right.

  26. Hi,

    is it possible to link to a Website via the Java Client API?

  27. Is there a way to edit the link relation instead of delete->create?

  28. Is there a way on a Confluence page to show all JIRA issues that are linking to that page?

     

    1. Hi Ethan,

      This is really more a Confluence query than JIRA. If your Confluence and JIRA instances are connected via application links, then when you check the Confluence pages' information (Tools > Page Information), you should see all the incoming links. Currently there is no macro available to show the linking pages on Confluence. However, there is a workaround which may work for you if you are technically minded.

      Thanks,

      Warren

  29. Hello!

    I want to clone issue with external links, but i don't see "clone links" checkbox. Is it possible to clone issue with external "http" links?

     

  30. When you use the advanced search feature to use JQL to identify the issues you want to link, why do these JQL results limit to just 10 results?  This is an impediment for us as we want to easily link all sprint issues or an epics issues to another issue (that we happen to use for releases), but there are more than 10 in the results, but we cannot get them returned.  I don't see anything that states you can only render 10 in the result list. Why?

  31. Hi all,

    I see the below error during creating an application link between confluence and jira.

    An Application Link from the remote application to this application is required to configure this authentication provider.

    I have whitelisted both the links and adding application link as admin user, Could someone help ?

    1. Hi clh,

      I'd suggest contacting support for help. They should be able to get you sorted out. 

      Thanks,

      Warren

  32. Re "deleting links", this only seems to work in the whole-page view of the issue, not the side-of-the-page version seen in an agile board.  There seem to be many things that don't work the same way in the two views (e.g. the screenshot plugin)

     

  33. Hi...

    How to select linked issue list?

    can you help me with this problem....

    tonertree.com

    1. Try Script Runner Plugin. It adds jql function to select like

      issuefunction in linkedIssuesOf("key = abc-123", "is Duplicated by")
  34. Is there a maximum number of linked issues in an issue?