# Jira Cloud integration > Install the Probara app in Jira, connect a Jira site to your organization, and map projects. The **Jira Cloud** integration connects a Jira Cloud site to your Probara organization. Once it is connected and a project is mapped, your team can create Jira issues from Probara defects, link issues that already exist, and keep status, priority and comments in sync in both directions. Test cases can be linked to Jira stories and epics for traceability, and a **Probara** panel on each Jira issue shows the linked cases, results and defects inside Jira. This guide covers setup: installing the app, connecting a site, choosing the Jira projects Probara may use, and mapping them to your Probara projects, one by one or with an organization default. Day to day: | Guide | Covers | | -------------------------------------------------------------------- | ------------------------------------------------------------------- | | [Jira issues from defects](https://docs.probara.net/en/guides/integrations/jira-defects/) | Creating and linking issues, and what syncs in each direction | | [Traceability with Jira](https://docs.probara.net/en/guides/integrations/jira-traceability/) | Linking test cases to Jira issues and building traceability reports | | [The Probara panel in Jira](https://docs.probara.net/en/guides/integrations/jira-panel/) | What Jira users see on an issue, and linking cases from Jira | ## Before you start | You need | Why | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | A paid plan (**Pro** or **Enterprise**, or any trial) | Integrations are not part of the Free plan. On Free, the Jira dialog shows **See plans** instead of **Install**. | | A Jira **site administrator** | Only a Jira site admin can install the app and start the connection in Jira. | | A Probara **owner** or **admin** | Only owners and admins of the organization can approve the connection and map projects. | | A Jira **Cloud** site (`https://.atlassian.net`) | Jira Data Center and Jira Server are not supported. | The Jira admin and the Probara admin can be the same person. The connection needs both sides on purpose: nobody can attach your Jira site to a Probara organization, or your Probara organization to a Jira site, from one side alone. ## Connect a Jira site 1. **Open the Jira app in Probara.** In **Workspace › Integrations**, select the **Jira Cloud** card. The dialog lists what the app can do and the three connection steps. 2. **Install the app in Jira.** Select **Install**. It opens the Probara for Jira installation page in a new tab; a Jira site admin completes the installation there. If **Install** is disabled with "The install link is not available in this environment yet", the app is not yet published for your environment — contact Probara support. 3. **Start the connection from Jira.** In Jira, open **Apps › Probara** (the app's admin page in the Jira administration area) and select **Connect with Probara**. Jira checks that you are a site admin, then opens Probara in a new tab. The Jira page switches to **Waiting for approval in Probara…** and updates on its own. 4. **Approve it in Probara.** Sign in if asked. If you belong to several organizations, pick the one to connect under **Workspace to connect** — this also switches your active workspace. Probara asks "Connect _your-site_.atlassian.net to _your organization_?" and shows when the link expires. Select **Connect**. 5. **Check both sides.** Probara shows **Jira is connected**; the Jira page shows **Connected to** _your organization_. The site now appears under **Connected sites** in the Jira dialog, with status **Active**. The connection link is valid for **10 minutes** and works **once**. If it expires, the Jira page shows **The connection link expired**: select **Start again** for a new one. Starting again also cancels any earlier link. ### More than one Jira site An organization can connect several Jira sites: repeat the steps from each site. A Jira site connects to **one** Probara organization at a time. If the site is already connected elsewhere, Probara answers "This Jira site is already connected to another workspace"; disconnect it there first. ## Choose which Jira projects Probara may use Each connected site has a list of **Allowed Jira projects**. Probara refuses to read, map, create issues in, or link issues from a Jira project outside the list, and searches only allowed projects. - To change it, select **Edit projects** on the site, enter the project keys separated by commas (for example `WEB, API`), and select **Save**. Keys are case-insensitive; a site can allow up to 100 projects. - **An empty list is not a restriction:** Probara can then use every project the app can see in Jira, and the site reads **All projects**. To limit Probara to specific projects, list them. - **The list also decides what Jira users see.** On issues of an allowed project, the Probara panel shows everyone who can browse the issue the Probara data linked to it; see [The Probara panel in Jira](https://docs.probara.net/en/guides/integrations/jira-panel/#what-jira-users-can-see). - Removing a project from the list does not remove existing mappings or links; it only blocks new work in that project. ## Map a Jira project to a Probara project A Probara project files its defects into the Jira projects mapped to it. You can map at two levels: | Level | Where | Applies to | | ------------------------ | -------------------------------------------------------------- | ----------------------------------------------------------- | | **Organization default** | **Workspace › Integrations › Jira Cloud**, **Default mapping** | Every project that has no mapping of its own | | **Project** | The project's **Settings › Jira** | That project only; it then ignores the organization default | To map one project: 1. Open the project's **Settings** and select the **Jira** tab. (The tab is shown only to owners and admins.) 2. Select **Add Jira project**. If the organization has several active sites, choose the **Jira site**. 3. Search for the **Jira project** by name or key and pick it. 4. Choose the **Issue type** your defects become in Jira (for example **Bug**). Subtasks are not offered. 5. Review the sections below, then select **Save mapping**. A Probara project can map several Jira projects, even from different sites. One of them can be the **default**: it is preselected when you create an issue, and it is the one used when a tester files a Jira issue while reporting a defect from a run. The first mapping is the default unless you uncheck **Use as the project's default Jira project**; use **Make default** in the list to change it later. ### Set a default mapping for the organization If most projects file defects into the same Jira project, map it once for the whole organization: 1. In **Workspace › Integrations**, select the **Jira Cloud** card. The **Default mapping** section appears below **Connected sites** once a site is connected, and stays while default mappings exist so you can remove them after disconnecting (owners and admins, paid plans). 2. Select **Add Jira project** and fill in the same dialog as for a project. Its checkbox reads **Use as the organization's default Jira project**. 3. Select **Save mapping**. How projects use the default: - **A project with no mapping of its own uses it right away.** Changes to the default apply to those projects immediately. Their **Jira** tab lists it as **Inherited from organization**. - **A project's own mapping replaces the default entirely.** Select **Customize for this project** on an inherited row (or **Add Jira project**) and save: the project now uses only its own mappings, never a mix with the default. - **Removing a project's last mapping** returns it to the organization default. - **Removing a default mapping** stops projects that use the default from filing new defects into that Jira project. Issues already linked keep their link. The sections below work the same at both levels. ### Status from Jira to Probara **When a Jira issue changes status** sets the linked defect's status by the Jira **status category**: | Jira status category | Default Probara status | | -------------------- | ---------------------- | | To do | **Open** | | In progress | **In progress** | | Done | **Resolved** | Under **Rules for specific Jira statuses**, you can give one Jira status its own Probara status — for example, send Jira's "Won't Do" to **Closed**. A status left on **Follow its category** uses the table above. ### Status from Probara to Jira **When a defect changes status** lets you choose, for each Probara status, the Jira status the linked issue moves to. Every status starts on **Don't change**, which never moves the issue. Probara moves the issue through your Jira workflow: it uses a transition that leads to the chosen status from where the issue is now. If the workflow offers none, the issue stays where it is and the link is not marked as failed. Changes that came from Jira are never sent back. ### Priority and severity - **Priority**: choose the Jira priority for each Probara defect priority. A new Jira issue gets the mapped priority, changing the priority in Probara updates the issue, and when someone changes it in Jira, the defect follows the same mapping back. A priority left on **Don't set** is not sent, and a Jira priority with no match leaves the defect unchanged. - **Severity**: Jira has no built-in severity. Pick one of your Jira single-select custom fields under **Jira field for severity**, then match each Probara severity to one of its options. It then syncs both ways like priority. Leave it on **Don't sync severity** to keep severity in Probara only. ### Required Jira fields If your Jira project requires fields on new issues (a component, a team, a custom field), **Required Jira fields** lists them. Fill in the values Probara should send on every issue created through this mapping. Fields Jira fills itself when left empty are marked as such and need no value. If a field type is one Probara cannot fill, give it a default value in Jira instead. Probara always sets the summary, description, project and issue type itself. ## Disconnect or uninstall | You want to | Do this | What happens | | ------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | Stop syncing from Probara | **Workspace › Integrations › Jira Cloud**, select **Disconnect** on the site and confirm. | The site leaves the list. Nothing is changed in Jira. Existing links stay on your defects but no longer update. | | Stop syncing from Jira | In Jira, **Apps › Probara**, select **Disconnect**, then **Disconnect site**. | Same result. It is recorded in your activity log as done by the system, with the Jira account. | | Remove the app | A Jira admin uninstalls Probara for Jira. | The site is disconnected from Probara and Probara discards the app's credentials. | To connect again, start from Jira with **Connect with Probara**. Reinstalling the app does not reconnect a site by itself: a Probara owner or admin must approve it again. Mappings of a disconnected site stay in the project's **Jira** tab (or the organization's **Default mapping**), marked **Disconnected site**, until you remove them. ## Troubleshooting the connection | You see | What it means | What to do | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | A site marked **Needs attention** | Probara cannot use the site's credentials — usually because it has not heard from the app for a while, or the app was removed from Jira without Probara being told. | Open **Apps › Probara** in Jira: any visit gives Probara fresh credentials, and the app renews them every hour on its own. If the app was uninstalled, install it and connect again. | | "No connected Jira site is reachable" in a project's **Jira** tab | Every connected site needs attention. | Fix the site as above. | | "Only Jira site administrators can connect or disconnect Probara." (in Jira) | Your Jira account is not a site admin. | Ask a Jira site admin. | | "Ask an owner or admin of _organization_ to connect Jira." | Your Probara role cannot approve connections. | Ask an owner or admin to open the link from Jira. | | "This link is invalid or has expired. Start again from Jira." | The link was used, expired after 10 minutes, or was replaced by a newer one. | Select **Start again** in Jira. | | "This Jira site cannot be connected yet." (in Jira) | The installation is not ready or its credentials are not usable yet. | Wait a minute and try again, or reinstall the app. | | "Too many attempts. Wait a moment and try again." | Connection attempts are rate limited per user and per site. | Wait and try again. | | "Connecting Jira is included in Probara's paid plans." | Your organization is on Free. | Change your plan, then start again from Jira. | ## Security and data - **Credentials.** The only credential Probara holds is the app's own Jira token, which Jira renews every hour. It is encrypted at rest (AES-256-GCM) bound to its installation, used only by Probara's servers, and never sent to your browser. Probara accepts calls from Jira only when they carry a token signed by Atlassian for this app. - **The connection link.** It is random, single-use and valid for 10 minutes. Probara stores only a hash of it, removes it from the address bar as soon as the page opens, and sends no referrer from that page. - **What Probara stores about your Jira site:** the site URL and Jira cloud id, and for each link the issue key, id and URL, its summary, status, priority and issue type. Comments written in Jira on a linked issue are copied to the defect with their author's Jira display name; restricted comments (visible only to a Jira group or role) are never copied. - **What Probara writes to Jira:** the issues you create (with the defect's details and, if you choose, its attachments); a **Probara** link on each linked issue pointing back to the defect or test case; a hidden issue property that tells the app which issues to send updates for; and, for linked defects, the status, priority and severity changes your mapping sends, and comments written in Probara. Comments name their author and mentioned members by first and last name only; Probara never sends email addresses to Jira. - **What Jira users see:** the Probara panel on an issue shows the Probara data linked to it to everyone Jira lets browse the issue, with no Probara account needed. See [The Probara panel in Jira](https://docs.probara.net/en/guides/integrations/jira-panel/#what-jira-users-can-see). - **Deletion.** Deleting the Probara organization deletes its project and default mappings, issue links and copied comments, including Jira author names. Probara never deletes issues in Jira. - **Audit.** Connecting, disconnecting, changing allowed projects, changing a project or default mapping, and linking or unlinking Jira issues on defects and test cases are recorded in [Workspace activity](https://docs.probara.net/en/guides/workspace/activity/). Links made from the Jira panel are recorded as done by the system, with the Jira account. ## Automate with the API and MCP Scripts, CI jobs and AI assistants can do the day-to-day Jira work with an [API token](https://docs.probara.net/en/developers/authentication/) or through [Probara MCP](https://docs.probara.net/en/developers/mcp/). Setup stays in the web app on purpose: connecting a site hands it to your organization, and a mapping decides where every future defect lands, so neither is something a leaked token should be able to do. | Works with an API token or MCP | Web app only (signed-in session) | | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | List, create, link, refresh and unlink a defect's Jira issues | Connecting a site (pairing) | | Search the Jira projects a project maps | Editing allowed projects, disconnecting a site | | List, link and unlink a test case's Jira issues; bulk link cases to one issue | Adding, changing and removing project and default mappings | | Build traceability reports and read their versions and requirements | Browsing a site's Jira projects, statuses and priorities for mapping | | Read a project's mappings (own or inherited) and a mapped Jira project's issue types and fields | | The same roles and plan apply as in the app. The MCP tools are `list_defect_jira_issues`, `create_defect_jira_issue`, `link_defect_jira_issue`, `unlink_defect_jira_issue`, `list_test_case_jira_issues`, `link_test_case_jira_issue`, `unlink_test_case_jira_issue`, `search_jira_issues`. The traceability tools are described in [Traceability with Jira](https://docs.probara.net/en/guides/integrations/jira-traceability/#automate-it). Every route and error code is in the [API reference](https://docs.probara.net/en/developers/api-reference/) under **Integrations**, and every tool in the [MCP tool reference](https://docs.probara.net/en/developers/mcp-tools/).