Skip to content
threada Docs

Atlassian setup and support

Threada for Jira is the planned Atlassian Marketplace Forge app for creating or linking governed Threada WorkItems from Jira issues. The first reviewable app is intentionally narrow: it uses a Jira issue panel, reads only the Jira issue/project context needed for intake, and shows setup, success, and approval or sync status in Jira. It does not perform unmanaged Jira writes, read attachments, export Jira data, read user directories, or execute third-party actions directly from Jira.

Threada also has the runtime Atlassian/Jira OAuth install binding needed by that Forge app: an admin can authorize an Atlassian 3LO app, Threada discovers the selected Jira Cloud site, and the BFF stores tenant-scoped credentials in Secret Manager. This runtime binding is necessary for reviewer testing, but it does not mean the Forge app has been publicly listed or approved.

This guide supports private Atlassian reviewer testing once a Forge review package is available and public Jira Cloud users after Atlassian approves and lists the app. Until the Atlassian Marketplace app is approved, existing Jira governed action payloads remain custom tenant integration work and should not be treated as the public Atlassian Marketplace app.

Requirements

Before installing or testing the Jira app, make sure you have:

  • An active Threada tenant.
  • Studio or Admin access for the Threada workspace that should receive Jira WorkItems.
  • A Jira Cloud site where you can install Forge apps, or an Atlassian administrator approval path.
  • Access to the Jira project and issue examples prepared for reviewer testing.
  • For private reviewer testing, the exact Forge app, distribution link, test site, and setup notes provided through the approved Atlassian review channel.
  • A configured Atlassian site, Jira project, issue context, or user mapping in Threada for the reviewed app package.

Do not use production customer Jira sites, customer issues, raw Jira exports, Forge invocation payloads, or screenshots containing private tenant data for Marketplace review evidence.

Install the Jira app

After Atlassian approves the public app, install Threada from Atlassian Marketplace. During private review, use only the Forge distribution or reviewer install path provided in the approved review notes.

  1. Open the target Jira Cloud site as an Atlassian administrator or approved reviewer.
  2. Install Threada for Jira from Marketplace or the private Forge distribution path.
  3. Confirm the app appears on a fresh Jira test site before relying on a reused developer site.
  4. Open the prepared Jira project and issue example.
  5. Confirm the Threada WorkItem issue panel is visible on the issue.

If the app cannot be installed, stop and fix the Forge app ID, production deployment, distribution setting, manifest scopes, remote endpoint, icon URL, or Atlassian Marketplace listing link before continuing.

Connect Jira to Threada

The Jira app must be mapped to a Threada tenant and receiving workspace before Jira users can create or link WorkItems.

  1. Sign in to Threada Studio with an admin or builder account.
  2. Open the workspace or pack that should receive Jira-created WorkItems.
  3. Start the Studio install handoff at https://studio.threada.ai/integrations/atlassian/install. If the reviewer or provider flow already knows the Jira Cloud site, include it as ?atlassian_site=<site-name>, ?jira_site=<site-name>, ?subdomain=<site-name>, or ?resource=<site-name>.
  4. Authorize the Atlassian/Jira OAuth app for the target Jira Cloud site. Studio redirects through /api/v1/integrations/atlassian/oauth/start?atlassian_site=<site-name> and returns to the pack connector readiness panel after authorization.
  5. Bind the installed Atlassian site, Jira project, issue context, or user context to the Threada workspace or pack.
  6. Select the receiving queue or routing policy.
  7. Save the mapping and run the connection test if one is available.

If the reviewed build does not yet expose a self-service Studio mapping UI, follow the reviewer setup notes for the exact Jira site, project, issue, Threada workspace, and queue prepared for review. Do not infer tenant mappings from Jira site names, project keys, issue titles, or user emails alone.

Open a prepared Jira issue and use the Threada WorkItem issue panel to create or link a governed Threada WorkItem.

After a successful request, Jira should show a clear success state and a safe Threada Work URL when available. Open the WorkItem in Threada and confirm the Jira source context is preserved, routing is correct, and the audit timeline records the intake event.

If Threada later creates or updates Jira issues from a WorkItem, those actions must run only through Threada governed action proposals with policy, approval, idempotency, and audit controls. The Marketplace app should not claim unmanaged Jira write behavior.

Setup-required responses

If the Jira app is installed but not connected to a Threada tenant or workspace, the issue panel should show a setup-required response instead of silently dropping the request.

Common setup issues:

  • The Atlassian site, Jira project, issue, or user context is not mapped in Threada.
  • The mapped Threada workspace or pack was disabled.
  • The receiving queue or routing policy is missing.
  • The Forge app package still uses placeholder app ID, icon, API URL, or Marketplace listing values.
  • The Forge app is deployed only to development or staging instead of a production-safe environment.
  • The Forge Remote endpoint is unavailable, not reachable over HTTPS, points to a non-production host, or does not validate Forge invocation context.
  • Jira permission checks or manifest scopes do not match the reviewed issue panel behavior.

For review builds, include the Atlassian site, Jira project key, issue key, approximate test time, and sanitized error text in support requests. Do not send OAuth secrets, access tokens, cookies, raw Forge invocation payloads, raw Jira issue exports, or private issue content.

Disconnect or uninstall

To stop Jira-created WorkItems:

  1. In Threada Studio, disable or remove the Atlassian mapping for the workspace, pack, site, project, or user context.
  2. In Jira, uninstall Threada from the relevant Atlassian site if it is no longer needed.
  3. Open a mapped test issue and confirm the issue panel returns setup-required feedback rather than creating a new WorkItem.

Disconnecting the app stops future intake. Existing WorkItems, messages, evidence, approvals, and audit events remain available in Threada according to the tenant retention policy.

Data handling

For v1, Threada receives only the Jira context needed to create, link, route, and audit a WorkItem from the issue panel. Threada should store Jira provenance as source metadata, channel IDs, tags, or equivalent audit context rather than raw Jira exports.

The v1 Forge issue-panel app requests read:jira-work only. The separate runtime Atlassian/Jira OAuth install requests read:jira-work, write:jira-work, and offline_access so Threada can retain the tenant-scoped install credential in Secret Manager and execute governed jira_create_issue or jira_update_issue actions when explicitly approved. Neither surface requests Jira admin, attachment, export, service-desk, or user-directory scopes. If a future version adds knowledge sync, attachment reads, broader site access, or additional Jira write surfaces, Threada must update this guide, explain the exact scope use, complete the required security and privacy review, and submit the updated app for Atlassian review before marketing the new capability.

Support

For setup help, contact support@threada.ai. For privacy or deletion requests, contact privacy@threada.ai. To report a security issue, contact security@threada.ai.

Support requests for the Jira app receive a response within 2 business days. Include the Threada tenant, Atlassian site, Jira project or issue key, app version when known, approximate test time, and sanitized error text. Do not send secrets, tokens, cookies, raw event payloads, customer exports, or private issue content.