> For the complete documentation index, see [llms.txt](https://docs.testfirst.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.testfirst.com/administration/integrations.md).

# Integrations

## Jira Integration Overview

Integrate **TestFirst with Jira** to connect your testing and issue-tracking workflows. Once configured, your team can create Jira issues from TestFirst, link tests to Jira issues, and view related TestFirst tests and results directly in Jira.

#### What You Can Do

With the Jira integration, you can:

* **Create Jira issues** from failed manual test results in TestFirst.
* **Link test cases** to existing Jira issues.
* **Link failed manual test results** to existing Jira issues.
* **View linked TestFirst test cases and test results** directly from Jira.

***

## Set Up the Jira Integration

Setting up the integration involves configuration in both **Jira** and **TestFirst**.

Complete the following steps:

1. **Create a dedicated TestFirst user** for the Jira app.
2. **Install and configure the TestFirst app in Jira** — completed once by a Jira Administrator.
3. **Configure the Jira integration in TestFirst** — completed once for the organization.
4. **Configure TestFirst projects** — map each required TestFirst project to its corresponding Jira project and issue type.
5. **Authenticate with Jira** — completed individually by each TestFirst user who needs to use Jira features.

***

### Install and Configure TestFirst App in Jira

Install the TestFirst app to display linked TestFirst tests and test results inside Jira.

This setup only needs to be completed **once by a Jira Administrator**.

#### Install the TestFirst App

1. Open the [**TestFirst app installation page**](https://developer.atlassian.com/console/install/49abde0f-591f-457b-b369-49056705c065/?signature=d630569e60d8353ab7e15e7574685e520dacc84f52b6c7bcb75133b0bd44cbc3\&product=jira) in your browser.
2. Click **Get app**. An *Install ‘TestFirst‘ by FirstCall QA* dialog will appear.
3. Select the **Jira site** where you want to install the app.
4. Click **Install**. The app will be installed on the selected Jira instance.

#### Configure the TestFirst App

1. In Jira, go to **Settings → Marketplace Apps**.
2. Find and open **TestFirst**.
3. Click **Allow access** when prompted.
4. Review the requested permissions and click **Accept**.
5. From the TestFirst welcome page, open the **TestFirst Admin Panel**.
6. Enter the credentials of the TestFirst user created for the Jira integration.

<figure><img src="https://2622859358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FErSaU4WjIuLC7zfVEh8L%2Fuploads%2FYwGcYHwjwFm4s9UwxtPX%2Fimage.png?alt=media&amp;token=a67de81b-2510-4202-9065-e3f9914f1da3" alt=""><figcaption></figcaption></figure>

7. Click **Login**.

Once connected, the TestFirst Jira app will be ready to display TestFirst information associated with Jira issues.

{% hint style="info" %}
We recommend creating a **dedicated TestFirst user** for the Jira app instead of using an existing user's account.
{% endhint %}

#### Additional Login Considerations

* **Google authentication is not supported** by the Jira app. If the account was created using Google authentication, set a password for the account before using it with the Jira app.
* If the TestFirst user belongs to multiple organizations, select the required organization when prompted and click **Proceed**.

***

### Configure Jira integration in TestFirst

After configuring the Jira app, connect your TestFirst organization to your Jira instance.

{% hint style="info" %}
The user performing this configuration must have the **Manage** permission for **Integrations**. See [**Roles and Permissions**](/administration/roles-and-permissions.md) for more details.
{% endhint %}

#### Configure the Integration

1. In the TestFirst web app, go to **Administration → Integrations**.
2. Click **Add Integration**.
3. Enter the integration details

<figure><img src="https://2622859358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FErSaU4WjIuLC7zfVEh8L%2Fuploads%2FuKbcTgAYN45rdMDuombt%2Fimage.png?alt=media&amp;token=42092a47-dbda-49a7-b650-fe3220d21a88" alt=""><figcaption></figcaption></figure>

| Field    | Description                              |
| -------- | ---------------------------------------- |
| Name     | Enter a name to identify the integration |
| Type     | Select **Jira**                          |
| Base URL | Enter the base URL of your Jira instance |

{% hint style="info" %}
Enter the base URL of your **Jira instance**, not the URL of an individual Jira project or issue.
{% endhint %}

5. Click **Save**.

The Jira integration will appear under **Integration Details**.

#### Manage the Integration

From **Integration Details**, you can:

* **Check** the Jira connection.
* **Edit** the integration configuration.
* **Delete** the integration.
* Open **Configured Projects** to manage project mappings.

***

### Project Configuration

Map each TestFirst project that uses Jira to its corresponding **Jira project** and **issue type**.

#### Configure a Project

1. Open the Jira integration under **Administration → Integrations**.
2. Click **Configured Projects**. The **Configured Test Projects** dialog will appear.
3. Find the TestFirst project you want to configure and click **Edit**.
4. Enter
   * **Project Key** – the key of the Jira project you want to connect.
   * **Issue Type** – the Jira issue type to use when creating issues from TestFirst, such as `Bug`.

<figure><img src="https://2622859358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FErSaU4WjIuLC7zfVEh8L%2Fuploads%2FZm1AFrMSdLYvCYgkhWN6%2FScreenshot%202026-08-21%20144016.png?alt=media&amp;token=22f0581f-c68b-430a-940d-e0bd0c70514b" alt=""><figcaption></figcaption></figure>

5. Click **Save**.

The project's **Jira Key** and **Issue Type** will be displayed, and the **Configured** column will indicate that the mapping is active.

{% hint style="info" %}
The **Project Key** and **Issue Type** must exactly match the values configured in Jira. The Issue Type is case-sensitive.
{% endhint %}

#### Jira Required Fields

When TestFirst creates an issue in Jira, it provides the Jira **Issue Type**, **Summary**, and **Reporter**.

If your Jira configuration requires additional fields when creating an issue, TestFirst may not be able to create the issue successfully. Review the required field configuration for the Jira project before using the integration.

#### Edit or Remove a Project Configuration

Click **Edit** to update the Project Key or Issue Type.

Click **Delete** to remove the Jira mapping. This removes only the integration configuration and does not delete either the TestFirst or Jira project.

***

### Authenticate with Jira in TestFirst

Each TestFirst user who wants to create or link Jira issues must authenticate individually using their own **Jira email address and API token**.

#### Authenticate with Jira

1. In TestFirst, go to **Administration → Integrations**.
2. Under **User Details**, click **Add User**.
3. Enter:
   * **Jira Email** – the email address associated with your Jira account.
   * **Jira API Token** – your Jira API token used to authenticate the connection.<br>

     <figure><img src="https://2622859358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FErSaU4WjIuLC7zfVEh8L%2Fuploads%2FUOG45NHLwzFrwtDSm606%2Fimage.png?alt=media&amp;token=88d26540-4f33-4b33-ae46-103d01997c2f" alt=""><figcaption></figcaption></figure>
4. Click **Save**.

Your Jira email will appear under **User Details**, and the **Authenticated** status will display a checkmark when authentication is successful.

{% hint style="warning" %}
Jira authentication is completed **separately for each TestFirst user**. Always use your own Jira credentials.
{% endhint %}

#### Manage Your Jira Authentication

Under **User Details**, you can:

* **Check** - verify your Jira authentication.
* **Edit** - update your Jira email or API token.
* **Delete** - remove your Jira authentication.

{% hint style="warning" %}
Jira API tokens are created and managed through your Atlassian account. Keep your API token secure and do not share it with other users.
{% endhint %}

***

## Using the Jira Integration

Once the setup is complete, TestFirst and Jira can be used together throughout your testing workflow.

### Link a Test Case to a Jira Issue

Test cases can be linked to existing Jira issues using the **Reference** field.

1. Create or edit a test case in TestFirst.
2. Add the **Jira issue URL** to the **Reference** field.<br>

   <figure><img src="https://2622859358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FErSaU4WjIuLC7zfVEh8L%2Fuploads%2FklMmJ7bp8K7qtXpNcUra%2FScreenshot%202026-08-21%20210739.png?alt=media&amp;token=7e4bea56-a5fe-4465-b1ee-b2d9dbd3e889" alt=""><figcaption></figcaption></figure>
3. Save the test case.

The linked Jira issue URL will be displayed in TestFirst, and the test case will appear in the [**TestFirst Test Cases** panel](https://docs.testfirst.com/administration/integrations#testfirst-test-cases) of the Jira issue.

***

### Create a Jira Issue from a Failed Manual Test Result

When submitting a **Failed** manual test result, you can create a new Jira issue directly from TestFirst.

#### Create a Jira Issue

1. Complete the test execution using manual testing app and set the test result to **Failed**.
2. Enter the failure **Summary** and **Details**.
3. Click **Submit Test Result**.
4. The **Associate Test Result with Issue** dialog will appear with the Summary and Details populated from the failure information.
5. Review the information.
6. Click **Submit**.

TestFirst creates the Jira issue using the **Issue Type** configured for the project (example: `Bug`).

The created Jira issue includes the test failure information and automatically adds an **Open 'Test Result' in TestFirst web** link to the **Steps to Reproduce** field. Click this link to open the associated test result directly in TestFirst.

Once the test result is submitted, a link to the newly created Jira issue will be displayed in TestFirst.

***

### Link a Failed Test Result to an Existing Jira Issue

Instead of creating a new Jira issue, you can associate a failed test result with an existing one.

1. In the **Associate Test Result with Issue** dialog, start entering the Jira issue key in **Link to existing issue**.
2. Select the required issue from the matching results.
3. Click **Submit**.

The test result will be linked to the selected Jira issue.

{% hint style="info" %}
When a failed test result is linked to an existing Jira issue, TestFirst adds a **comment containing the test result details** to the Jira issue.
{% endhint %}

***

### View TestFirst Test Cases and Test Results in Jira

After the TestFirst Jira app is installed and configured, linked testing information is displayed directly on Jira issues.

#### TestFirst Test Cases

The **TestFirst Test Cases** panel displays test cases that reference the Jira issue.

<div align="left"><figure><img src="https://2622859358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FErSaU4WjIuLC7zfVEh8L%2Fuploads%2Fi563k57K1cjTGYF0Wb3o%2FScreenshot%202026-08-21%20211417.png?alt=media&amp;token=8b97a623-9335-49d7-9af8-075c3b921228" alt="" width="298"><figcaption><p>Use "View app actions" icon to open TestFirst Test Cases panel </p></figcaption></figure></div>

<figure><img src="https://2622859358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FErSaU4WjIuLC7zfVEh8L%2Fuploads%2FXX2yLZsYIIXDxWKcFuFE%2FScreenshot%202026-08-21%20211648.png?alt=media&amp;token=b9fd3c97-6c65-4bd8-b62f-c29766007162" alt=""><figcaption></figcaption></figure>

From the panel, you can open a test case in a modal, a new browser tab, or directly in TestFirst.

If no test cases reference the Jira issue, **No Results Found** will be displayed.

***

#### TestFirst Test Results

The **TestFirst Test Results** panel displays test results associated with the linked test cases.

<div align="left"><figure><img src="https://2622859358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FErSaU4WjIuLC7zfVEh8L%2Fuploads%2FvsFWLi9nfDMyotMjrTbV%2Fimage.png?alt=media&amp;token=64fd0d0c-e862-4ed8-942d-bc4e8ad25555" alt="" width="287"><figcaption><p>Use "View app actions" icon to open TestFirst Test Results panel </p></figcaption></figure></div>

<div align="left"><figure><img src="https://2622859358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FErSaU4WjIuLC7zfVEh8L%2Fuploads%2FXeFvNfRS8FeLKqwHDQ9R%2Fimage.png?alt=media&amp;token=f1b8def5-9086-43b3-b2e4-51eda66caf49" alt="" width="563"><figcaption></figcaption></figure></div>

You can open test results in a modal, a new browser tab, or directly in TestFirst.

Both Jira panels display up to **five rows per page**. Pagination is available when additional results exist.