Atlassian Jira

This guide was written specifically for integrating the Atlassian Jira Cloud product with FOSSA, although this will likely work if you are using a Jira Server/on-premises version as well.

There are two main features of FOSSA's Jira integration:
1) The ability to export FOSSA issues as new tickets in Jira.
2) The ability to resolve issues within Jira and have the linked FOSSA issue resolved automatically.

Setup and Configuration

In order to configure these two features, you will need to first obtain/create some permissions within Jira:

• To export issues: Jira "Product Access" is required.
• To resolve issues: Jira "Administration Access" is required (to create the webhook).

A permission group can be created to inherit both Product and Administration permission to give the user of that group access to both.

To integrate Jira with FOSSA, head over to the Jira integration settings page (/account/settings/integrations/jira). This page allows you to configure your Jira site integration(s). Start by clicking Add Site if you have not set it up previously.

Name and Site URL

Give your Jira site a unique name (only relevant if setting configuring multiple Jira integrations), and then input your Jira site URL. Note that this should just be the base URL, for example if using Jira cloud it might be something like your-org.atlassian.com.

Project Key(s)

Every Jira project has a key, usually a 3-4 character unique identifier. You'd be able to see this in the URL of the project, and it is used as the prefix for all issue IDs within that project. You can also find it in the right-hand details panel of each project summary, under Key.

You can include multiple projects (for example, if your frontend and backend teams use different Jira projects to track issues), but you must include at least one project key.

Issue Types and Labels

Issue types map directly to the types of issues you have configured in Jira, so type them exactly as they appear there. Examples of default issue types include "Bug" and "Task". Labels don't need to be predefined in Jira, so you can input anything you wish to label FOSSA-exported issues with.

📘

Tip:

Users often like all FOSSA exported issues to use the same label or issue type for easier tracking, so perhaps create a new "FOSSA" label or issue type within your Jira site.

Credentials

You'll need to authenticate with Jira in order to integrate successfully. Enter the email of a user who has permission to create and resolve issues (consider creating a new "FOSSA user" within your Jira instance).

API Token: Jira Cloud

Jira Cloud allows users to create API tokens that integrations such as FOSSA can use to communicate with Jira on the user's behalf. FOSSA requires that a Jira user with permission to create, resolve, and modify users create the API token.

You can follow this guide for creating a new API token.

When configuring your Jira site in FOSSA, use the username of the Jira user that created the API token, and use the API token as the user's password.

API Token: Jira Server/On-prem

For Jira Server/on-prem users, you will need to create a new user for FOSSA within your Jira instance.

1. Create a new user:

Specify whatever username/password you'd like in the screen above. By default, we keep the combination fossabot/fossa123.

2. Add user as an admin

Custom Fields

❗️

IMPORTANT

FOSSA supports exporting issues with simple text-based custom fields. To configure a custom field in Jira, follow this guide.

You can integrate custom fields with FOSSA by doing the following on the Jira settings page:

1. In the Jira integration settings page, click Add Field under the custom fields section.
2. Enter the Field ID of the custom field. You can find this ID in your Jira site by clicking on:
   • Project Settings

- In the sidebar: Issues > Fields

- Clicking on the Edit button at the top right of the table (the pencil).

- Click Edit on the field you wish to add.
- In the URL, you will find something like `orderableFieldId=customfield_10031`

- All you need is the numeric portion a the end of the ID (eg: `10031`)

3. Add a display name (usually the same name the field has in Jira).
4. Optionally include a default value for the field.
5. If you want all issues to include this field when exported from FOSSA, ensure that "required" is selected.

Headers

If your Jira configuration requires additional request headers (perhaps for authentication), you can set them at the bottom of the Jira settings page. This is an advanced feature and you probably don't need to worry about it if you are integrating with Jira Cloud.

Webhooks

Once you save your Jira site settings, a webhook URL will be generated for you. FOSSA requires webhooks to sync issue status with Jira. This means that when a user closes an issue in Jira, the corresponding issue will be resolved in FOSSA.

In order to tell Jira about this webhook, follow these steps:

1. In Jira, navigate to Admin > System > Advanced > WebHooks.

2. Create a new webhook.

3. Enter in your FOSSA IP/Port with the path specified below. Note that the webhook URL is different for each Jira site that you configure in FOSSA.

4. Define events for updating/deleting issues:

5.Then click the Create on the bottom of the form. The created webhook should look something like:

Troubleshooting

Overview

This guide provides systematic troubleshooting steps for FOSSA's Jira integration issues. Based on analysis of support tickets (particularly TKT-13433), most Jira integration failures are not permissions issues but rather field configuration or API compatibility problems.

Common Error Patterns

Generic Error Message

"Failed to create issue. Make sure the configured Jira account has permission to create issues in the target Jira project."

Important: This error appears for multiple root causes, not just permissions issues.

Diagnostic Workflow

Step 1: Verify Basic Configuration

1. Check FOSSA Integration Settings

   • Site URL format: https://yourcompany.atlassian.net/
   • Project keys exist in Jira
   • Username format: [email protected] (not display name)
   • API token is valid and current

2. Verify Jira Permissions

   • User has "Create Issues" permission
   • User can access the target project
   • User can create the specified issue type manually

Step 2: Test Manual API Calls

Before assuming permissions issues, test FOSSA's exact API calls manually:

Single Issue Creation Test

curl -X POST "https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue" \
  -H "Content-Type: application/json" \
  -u "[email protected]:YOUR_API_TOKEN" \
  -d '{
    "fields": {
      "project": { "key": "YOUR_PROJECT_KEY" },
      "summary": "Test FOSSA Integration",
      "description": "Testing API compatibility for FOSSA integration",
      "issuetype": { "name": "Bug" },
      "labels": ["FOSSA"]
    }
  }'

Bulk Issue Creation Test

curl -X POST "https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue/bulk" \
  -H "Content-Type: application/json" \
  -u "[email protected]:YOUR_API_TOKEN" \
  -d '{
    "issueUpdates": [
      {
        "fields": {
          "project": { "key": "YOUR_PROJECT_KEY" },
          "summary": "Test FOSSA Bulk Integration",
          "description": "Testing bulk API compatibility for FOSSA integration",
          "issuetype": { "name": "Bug" },
          "labels": ["FOSSA"]
        }
      }
    ]
  }'

Troubleshooting Checklist

Basic Configuration

• FOSSA integration enabled and saved
• Jira site URL correct (with trailing slash)
• API token valid and not expired
• Username is email address, not display name
• Project key exists and is accessible

Field Configuration

• Issue type exists in project
• Description field enabled for issue type
• Summary field enabled and required
• No required custom fields blocking creation

Permissions

• User can manually create issues in target project
• User has "Create Issues" permission
• User can access the project
• API token has appropriate scopes

API Testing

• Manual API calls succeed with same credentials
• Bulk API calls work
• Error responses provide specific field information

Advanced Debugging

Enable Jira API Logging

1. Go to Jira Administration → System → Logging and profiling
2. Add package: com.atlassian.jira.rest
3. Set level to DEBUG
4. Reproduce the issue
5. Check logs for specific API call details

Network Connectivity

# Test connectivity to Jira
curl -I "https://yourcompany.atlassian.net/"

# Test API endpoint accessibility
curl -u "email:token" "https://yourcompany.atlassian.net/rest/api/2/myself"

FOSSA Debug Information

1. Check FOSSA logs for integration attempts
2. Look for specific error codes or API responses
3. Verify integration configuration in FOSSA database

Support Escalation

Escalate to engineering when:

• Manual API calls work but FOSSA integration fails
• Field configurations are correct but integration still fails
• API responses suggest FOSSA is sending malformed requests
• Multiple customers report the same integration pattern failure

Include in escalation:

• Complete API test results (both success and failure cases)
• Jira project configuration details
• FOSSA integration settings
• Specific error messages from API responses (not just FOSSA UI messages)

When FOSSA generates a ticket, by default it sets the Jira issueType to be Task. This is one of the default issue types for new Jira installations, but your admin may have deleted/configured out this issue type or your installation could just be missing it. Check on the existing issue types in Jira and create the Task type if it is missing.

See the Jira help doc for more instructions.