Documentation for FishEye 3.0.x. Documentation for other versions is available too.

Skip to end of metadata
Go to start of metadata

JIRA is Atlassian's issue tracking and project management application.

When FishEye is integrated with JIRA, you can:

This page describes how to integrate JIRA with FishEye.

Initial configuration

You should check that JIRA is configured to accept remote API calls; in JIRA, go to Administration > System > General Configuration and turn on Accept remote API calls (under 'Options'). A restart is not required.

See JIRA options for more detail.

Quick setup with the FishEye Setup Wizard

When you are installing FishEye, the setup wizard allows you to configure the JIRA connection automatically. This is a quick way of setting up your JIRA integration with the most common options. See Configuring JIRA Integration in the Setup Wizard.

If you did not set up the JIRA integration during the FishEye setup, you can configure the integration via the FishEye administration screens as described below.

JIRA integration within FishEye

You can further configure the JIRA connections using the FishEye administration screens. There are two parts to the integration process:

  • A peer-to-peer link between JIRA and FishEye, for sharing information and facilitating integration features. This link is set up with Application Links.
  • A client-server link between FishEye and JIRA, for delegating user and group management to your JIRA server.

1. Configuring the application links with JIRA

Below are instructions for creating a two-way trusted applications link between FishEye and JIRA. We assume that your FishEye and JIRA servers are using the same set of users. If not, please refer to Adding an Application Link for information about the various options available.

To add a two-way trusted applications link between FishEye and JIRA:

Go to your FishEye administration screen and add the application link:

  1. Click 'Add Application Link'. Step 1 of the link wizard will appear.
  2. Enter the server URL of the application that you want to link to (the 'remote application').
  3. Click the 'Next' button.
  4. Enter the following information:
    • 'Create a link back to this server' – Tick this check box to add a two-way link between the two applications.
    • 'Username' and 'Password' – Enter the credentials for a username that has administrator access to the remote application.
      Note: These credentials are only used to authenticate you to the remote application, so that Application Links can make the changes required for the new link. The credentials are not saved.
    • 'Reciprocal Link URL' – The URL you give here will override the base URL specified in your remote application's administration console, for the purposes of the application links connection. Application Links will use this URL to access the remote application.
  5. Click the 'Next' button.
  6. Enter the information required to configure authentication for your application link:
    • 'The servers have the same set of users' – Tick this check box, because the users are the same in both applications.
    • 'These servers fully trust each other' – Tick this check box, because you trust the code in both applications and are sure both applications will maintain the security of their private keys.
      For more information about configuring authentication, see Configuring Authentication for an Application Link.
  7. Click the 'Create' button to create the application link.


2. Connecting to JIRA for user management

This option is available only with JIRA 4.3 and later.

If you want to manage your FishEye users using JIRA, you need to configure a connection in JIRA and then set up the user directory in FishEye. Both steps are described below.

2.1. To configure a new connection for user management in JIRA:

  1. Log in to JIRA as a user with the 'JIRA System Administrators' global permission.
  2. Click Administration on the JIRA top navigation bar.
    1. Go to the JIRA administration screen for configuring the applications that have been set up to use JIRA for user management:
      • In JIRA 4.3: Click 'Other Applications' in the 'Users, Groups & Roles' section of the JIRA administration screen.
      • In JIRA 4.4: Select 'Administration' > 'Users' > 'JIRA User Server'.
    2. Add an application.
    3. Enter the application name and password that your application will use when accessing JIRA.
    4. Enter the IP address or addresses of your application. Valid values are:
      • A full IP address, e.g.
      • A wildcard IP range, using CIDR notation, e.g. For more information, see the introduction to CIDR notation on Wikipedia and RFC 4632.
      • Save the new application.

2.2. To set up the JIRA user directory in FishEye:

  1. Go to your FishEye administration screen.
    1. Click Authentication (under 'Security Settings').
    2. Click Setup JIRA/Crowd authentication. Note, if LDAP authentication has already been set up, you will need to remove that before connecting to JIRA for user management.
    3. Make the following settings:

      Authenticate againstSelect a JIRA instance
      Application name and passwordEnter the values that you defined for your application in the settings on JIRA.
      JIRA URL

      The web address of your JIRA server. Examples:
      Auto-addSelect Create a FishEye user on successful login so that your JIRA users will be automatically added as a FishEye user when they first log in.
      Periodically synchronise users with JIRASelect Yes to ensure that JIRA will synchronize all changes in the user information on a regular basis. Change the value for Synchronise Period if required.
      When Synchronisation HappensSelect an option depending on whether you want to allow changes to user attributes from within FishEye.
      Single Sign OnSelect Disabled. SSO is not available when using JIRA for user management and if enabled will make the integration fail.
    4. Click Next and select at least one user group to be synchronised from JIRA. If necessary, you could create a new group in JIRA, such as 'fisheye-users', and select this group here.
    5. Click Save.


We do not recommend the use of project links with FishEye 2.9 and later, if you have JIRA 5.0 or later as well as the latest version of the JIRA FishEye Plugin. This is because application links now provide all of the functionality previously available with project links. However, project links are retained for the following reasons:

  • Setting up project links provides a way to restrict the scope of JIRA searches to a specific FishEye repository. 
  • Legacy configurations can continue to use project links without any need for changes.
  • Third-party plugins may continue to rely on project links for their functionality.

See Configuring Project Links across Applications.


  • JIRA requires FishEye to manually refresh repository cache when repository changes are made — When a repository is removed, or when there has been any change in FishEye repositories, JIRA does not update the FishEye repository list cache automatically. You must manually refresh the repository list cache. This is done in JIRA: 'Administration' > 'FishEye Configuration' > 'Refresh Cache' link (next to 'Repository List Cache')
  • FishEye doesn't check for invalid JIRA issue keys – FishEye doesn't check for invalid issue keys, such as UTF-8. An error will result if FishEye tries to connect to an issue that doesn't exist.
  • FishEye doesn't recognise custom JIRA issue key formats – FishEye assumes that JIRA issue keys are of the default format for JIRA 5.0 and later: that is, up to 10 letters, followed by a hyphen and the issue number (i.e. [a-zA-Z]{10}-[0-9]+), for example FishEye-123
  • If FishEye/Crucible will be running on the same machine as JIRA (already installed), you need to ensure that the URL paths are different for FishEye/Crucible and JIRA. Change the default FishEye/Crucible path as follows:
    • Edit the config.xml in your FishEye/Crucible data directory.
      Add the context attribute to the web-server  element:

      <web-server context="/fisheye">
  • No labels


  1. In step 2.2, I cannot see the option authenticate against a JIRA instance. Only crowd can be seen. Please help! (sad)


    • JIRA 5.2 with LDAP authentication
    • Fisheye+Crucible 2.9.2
    • application links are successful.

    1. Hello Metan,

      I think you will need to remove your LDAP configuration first, as mentioned in Step 2.2 1b. Please see if this helps.

      regards, Paul

  2. Is there still an open issue with getting this to work for some?  I've recreated my Application Link with JIRA and still FishEye cannot update an issue.  We get "FishEye was unable to comment on the issue XX-123 because JIRA responded with the following error: You do not have the permission to comment on this issue."

    I have all of the latest plugins and versions of everything installed.  I can submit a support ticket if need be.

  3. Anonymous

    We are using a standalone installation of JIRA 5.2.4 and FIshEye 2.10.0 and the only way I've gotten Smart Commits to work is using outgoing OAuth authentication from FishEye to JIRA, which unfortunately requires users to sign-in to FishEye and authenticate every 30 days.