Linking Crucible to JIRA

Linking Crucible with JIRA instances

You can integrate Crucible with one or more instances of JIRA from the Crucible administration area. There are two parts to integrating with a JIRA instance:

• Setting up an application link between JIRA and Crucible, described below, for sharing information and facilitating integration features.
• Linking Crucible with JIRA for delegating user and group management to your JIRA server. You would only do this with one instance of JIRA.

Configuring an application link with JIRA

This section describes how to create a two-way applications link between Crucible and JIRA. 

To create a new application link between Crucible and JIRA:

1. Go to your Crucible administration screen and click Application Links (under 'Global Settings').
2. Enter the URL for the JIRA instance you want to link to and click Create new link.
3. Complete the application link wizard to connect Crucible to your JIRA server. You must make use of the automatic link-back from JIRA to Crucible to get full integration (you'll need the JIRA system administrator global permission for that).

For FishEye 3.2 and later, creating a new application link now uses OAuth by default and enables both 3-legged OAuth (3LO) and 2-legged OAuth (2LO).

To update an existing application link with JIRA:

When you update an older application link to use OAuth, 3-legged authentication is applied by default. However, you'll need to explicitly enable 2-legged authentication in order to see Crucible information in the JIRA Development panel (when integrated with JIRA 6.2 or later).  Enable 2LO for the application link as follows:

1. Go to the Crucible admin area and click Add-ons > Application Links.
2. Click Edit for the app link with JIRA.
3. For both Outgoing Authentication and Incoming Authentication:
   1. Click OAuth
   2. Check Allow 2-legged OAuth.
   3. Click Update.

The application link update process will involve you logging into JIRA for a short time to configure the JIRA end of the link, before returning you to the Crucible.

Connecting to JIRA for user management

This option is available only with JIRA 4.3 and later.

To manage your Crucible users using JIRA, configure a connection in JIRA and then set up the user directory in Crucible. Both steps are described below.

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. 192.168.10.12.
      • A wildcard IP range, using CIDR notation, e.g. 192.168.10.1/16. For more information, see the introduction to CIDR notation on Wikipedia and RFC 4632.
      • Save the new application.

To set up the JIRA user directory in Crucible:

Go to your Crucible 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 against	Select a JIRA instance
   Application name and password	Enter the values that you defined for your application in the settings on JIRA.
   JIRA URL	The web address of your JIRA server. Examples: http://www.example.com:8080/jira/ http://jira.example.com
   Auto-add	Select 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 JIRA	Select 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 Happens	Select an option depending on whether you want to allow changes to user attributes from within FishEye.
   Single Sign On	Select 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.

Inline issue creation

Inline issue creation allows a user to create a JIRA issue from a review comment. The user must have the 'Comment' permission in Crucible to see the Create Issue link in the comment. See Creating JIRA issues from the review.

This requires that Crucible is integrated with JIRA 5.0, or later, and is disabled if Crucible is integrated with an earlier version of JIRA.

When creating the issue, the Create Issue dialog only displays required fields for the selected issue type.

• A JIRA administrator can configure other fields to be required (and so displayed) from within JIRA. See Specifying Field Behaviour. 
• Not all field types are supported. In particular, unbundled custom field types are not supported. See Supported fields for inline issue creation.
• If any required field for the selected issue type is not supported, Crucible displays an error, with a link to create the issue directly in JIRA. This link will pre-populate the project, issue type, summary and description fields, but will not create a link from the comment to the issue. 

In the new issue in JIRA, you see a link back to the comment in Crucible. However:

• Issue links may be disabled in JIRA.
• The JIRA login that Crucible uses needs permission to create links.
• The FishEye plugin (available from the Atlassian Marketplace) must be installed in JIRA for permission checking on the display of issue links in JIRA.

You can disable the Inline Issue Creation plugin in Crucible to restore the earlier behaviour.