Skip to content

Getting started

This page takes you from a fresh installation to a project where link rules are enforced. Each step links to the page with the details.

After installation nothing is restricted: until a project administrator turns control on, Issue Link Guard lets everyone link with every link type, exactly as Jira does.

1. Install the app

A Jira administrator installs Issue Link Guard from the Atlassian Marketplace. The app's pages appear in:

  • Jira admin settings → Marketplace apps → Issue Link Guard, for Jira administrators,
  • Project settings → Apps → Issue Link Guard in every project, for project administrators. In the new Jira navigation, project settings are called Space settings.

2. Set the rules for a project

A project administrator opens the project's Issue Link Guard settings and:

  1. Turns on Control enabled for this project.
  2. Chooses a control mode. The default, General model, is one table of link types for the whole project.
  3. For each link type, switches Allowed on or off and, with Edit, chooses who can use it.
  4. Optionally turns on Show the Issue Link Guard panel on issues, so that users can link from the issue view without any custom field.
  5. Selects Save.

Details: Link rules and Side panel and link window.

At this point the rules apply to everything users do through Issue Link Guard. Users who still have Jira's "Link Issues" permission can bypass them through Jira's built-in "Linked work items" section. Step 4 closes that gap.

3. Optional: add the fields

A Jira administrator can create custom fields of two types and add them to the project's screens:

  • Issue Link Guard – Links opens a window with all links of the issue, where users add and remove links of the types they are allowed to use. On the create screen, users choose the links for the new issue.
  • Issue Link Guard – Picker links with one configured link type and offers only issues that match a JQL filter. It can hold one issue or many.

A field appears on issues only when it is on the screens the project uses. Creating the field alone is not enough.

Details: Links field and Picker fields.

4. Make the rules binding

A Jira administrator:

  1. Opens Jira admin settings → Marketplace apps → Issue Link Guard → Technical account.
  2. Selects Set up… next to the project and then Turn on the technical account.
  3. In the project's permission scheme, removes Link Issues from the users and groups who should link only through the app. Keep the entry for the project role atlassian-addons-project-access: the app's account gets its permission through it.

From then on, links made through Issue Link Guard in that project are created by the app's account, after the app has checked the project's rules for the person who asked for the link.

Details and warnings about shared permission schemes: Technical account.

5. Check the activity log settings

Every link created or removed through the app is recorded in the issue's activity log. By default the log keeps entries for 24 months. A Jira administrator can change this, anonymize entries or turn the log off on the Data and privacy tab: see Data and privacy.