Skip to content
threada Docs

Atlassian Marketplace

This guide defines the Atlassian Marketplace path after Slack Marketplace, the Zapier public integration scaffold, Microsoft Teams Store scoping, and Google Workspace Marketplace scoping. It is a design and launch-control document, not evidence that an Atlassian Marketplace app has been deployed or approved.

Current Status

Atlassian Marketplace is planned as a public store follow-on. Threada already has governed Jira action proposal payloads for jira_create_issue and jira_update_issue in the public API action model, plus a runtime Atlassian/Jira OAuth 3LO install binding that discovers the authorized Jira Cloud site and stores tenant-scoped credentials in Secret Manager. A private Forge manifest scaffold exists at packages/atlassian-marketplace-app for a narrow Jira issue-panel v1, and public setup/support guidance lives in Atlassian setup and support. No Atlassian developer console app, production Forge deployment, Marketplace listing, Forge issue panel UX, Atlassian security ticket, or Marketplace approval evidence has been observed in this repository.

Do not submit or market a public Atlassian Marketplace listing until the chosen Jira app package is deployed in a reviewer-safe test site, validated end to end, linked to a Marketplace listing, and accepted by Atlassian review.

The existing Jira action payloads remain tenant-specific governed action work. They should not be described as the public Atlassian Marketplace app.

The enterprise-safe first package should remain the committed Forge Jira issue panel scaffold that creates or links a governed Threada WorkItem from Jira context and shows the Threada approval or sync status back inside Jira. A Jira issue panel is the right first surface because it can appear inside a Jira issue, use issue/project context, and keep the reviewer journey concrete.

The current jira_create_issue and jira_update_issue payloads are useful implementation evidence for outbound governed proposals from Threada into Jira. They are not enough for Marketplace by themselves because Atlassian reviewers need an installable app package, declared Jira scopes, visible Jira UX, third-party-account setup notes, and security/privacy evidence.

The shared Marketplace OAuth install binding is the correct runtime foundation for the issue-panel app, but it is still not a Marketplace launch claim until the Forge package calls it from the reviewed Jira flow and the selected Atlassian Cloud ID is mapped to a Threada tenant, pack, queue, or workspace.

Positioning

Threada for Jira should connect Jira work to governed Threada WorkItems without bypassing Threada policy, approval, idempotency, and audit controls.

The narrow v1 app should stay focused:

  • Create or link a governed Threada WorkItem from a Jira issue, project page, issue action, or another Forge-supported Jira entrypoint.
  • Bind the installed Atlassian site, Jira project, issue context, or user context to a Threada tenant, pack, queue, or workspace mapping.
  • Show clear success, setup-required, and approval-pending states inside Jira.
  • Support outbound governed proposals from Threada to create or update Jira issues only through approved, auditable Threada action flows.
  • Provide public setup/support documentation that explains least-privilege Jira scopes, data handling, uninstall, and disconnect behavior.

The v1 app must not claim that Jira can execute arbitrary third-party actions through Threada. Direct external execution remains inside Threada’s governed Work, Studio, MCP, A2A, or first-party runtime paths.

Source Of Truth

Do not duplicate request or response schemas in this document. Public WorkItem shape and governed action proposal behavior are documented in Threada Public API and its generated OpenAPI artifact at /openapi/public-api.openapi.yaml. The committed source copy is docs/developers/public-api.openapi.yaml.

The private Forge scaffold lives at packages/atlassian-marketplace-app and generates dist/manifest.yml, dist/manifest.json, dist/marketplace-listing.json, and dist/readiness.json from src/forge-app.template.json. The scaffold is the source of truth for the planned v1 manifest posture only: Jira issue panel, read:jira-work, one explicit hosted icon URL, one explicit Threada API egress host, and no Jira write/admin/export/attachment/user-directory scopes. The public setup/support URL for the package is https://docs.threada.ai/integrations/atlassian-setup/.

The runtime install path lives in public-bff under /api/v1/integrations/atlassian/oauth/start and /api/v1/integrations/atlassian/oauth/callback. It uses Atlassian OAuth 2.0 3LO, discovers accessible Jira Cloud resources, stores installed credentials under the shared marketplace Secret Manager prefix, and upserts a Jira IntegrationType record with the jira_issue_context_v1 capability set and runtime-enforced jira_create_issue and jira_update_issue action allowlists.

The Studio public install handoff for reviewers and future Marketplace listing copy is https://studio.threada.ai/integrations/atlassian/install. Studio resolves the authenticated tenant and pack, preserves an optional Jira site selection as atlassian_site, and redirects through the BFF OAuth start route before returning to the connector readiness panel.

When a deployed Atlassian Marketplace package exists, the Forge app manifest, Jira modules, least-privilege scopes, remotes/providers, installation mapping, listing metadata, security ticket output, approval result, and reviewer setup notes must become the source of truth for the public listing.

App Surface

The first reviewable capability should create or link a Threada WorkItem from Jira context through the committed Jira issue-panel scaffold. Follow-on issue actions, project pages, or other Forge-supported Jira modules should wait until the issue-panel flow is deployable, mapped to a Threada tenant, and reviewable end to end without customer data.

Inputs should map Jira issue context to the live WorkItem fields for subject, channel, channel ID, thread/source metadata, contact details where allowed, tags, and initial message. Use an existing accepted public API channel label, such as custom or api, until the public API contract includes a dedicated Jira label. Preserve Jira provenance in channel IDs, tags, or source metadata rather than inventing a new public API enum value in docs.

Outputs must give the Jira user a clear success or setup-required state and a safe Threada Work URL when one can be generated. Do not return only a generic success message; Marketplace reviewers need to see the actual Jira-to-Threada journey.

Setup And Tenant Mapping

The app must bind an installed Atlassian site, Jira project, issue context, or user context to a Threada tenant, pack, queue, or workspace mapping before claiming production readiness. If setup is incomplete, the app should show a clear setup-required response instead of silently dropping the request.

Reviewer setup notes must include the exact Atlassian test site, Jira project, users, issue examples, and Threada workspace or pack mapping needed to exercise the app. Credentials, tokens, cookies, raw event payloads, and customer data must stay out of repo evidence and screenshots.

Governed Jira Create And Update Proposals

Threada already exposes governed action payload types for creating and updating Jira issues. A Marketplace v1 can reference those capabilities only as governed proposal flows from Threada back to Jira after the Forge app proves install, permission, mapping, and audit behavior.

The listing must not imply unmanaged Jira writes. Issue creation, transitions, comments, or updates should execute only after the configured Threada policy and approval path permits them, and the resulting Jira action should leave an auditable WorkItem trail.

Marketplace Package Requirements

Atlassian’s Forge listing guidance says Marketplace listing work requires linking the Forge app to the listing and being ready to explain required API scopes, remote hosts, and policy/compliance information. Atlassian’s launch guidance calls out support, privacy, security, and data-handling readiness. Forge permissions guidance says scopes should be declared through the manifest and kept to the minimum needed for the app. Forge Remote guidance requires HTTPS remotes and validation of incoming Forge requests when a remote backend is used. Atlassian’s approval guidelines require public apps to perform as described, provide setup/use documentation, privacy policy, secure authentication, security workflow evidence, marketing assets, and integration testing credentials when a third-party service is required.

The committed scaffold covers the local manifest/listing source shape, but not runtime deployment or Marketplace readiness. Required package work before submission:

  • Promote the generated manifest.yml into a deployed Forge app with a real Atlassian Forge app ID, declared Jira issue-panel module, resources/resolver, least-privilege Jira scopes, and production-safe endpoints.
  • Run Forge lint/precheck validation, deploy to a production-safe environment, enable distribution, link the Forge app to the Marketplace listing, and validate install on a fresh Jira Cloud test site.
  • Keep the v1 app surface to the Jira issue panel until the panel flow is installed, mapped, and smoke-tested.
  • Tenant/site/project install mapping, setup-required behavior, WorkItem creation or linking, status feedback, and uninstall or disconnect handling.
  • Production Threada endpoints for any Forge Remote calls, with Secret Manager or approved managed identity storage for credentials.
  • Validation of Forge invocation tokens and user permissions before executing user-context actions when Forge Remote or external services are used, plus evidence for egress host allowlisting, logging, encryption, tenant isolation, and incident response.
  • Public support, privacy, terms, security/data-handling, and setup documentation.
  • Marketplace listing copy, logo/banner/screenshots, test instructions, setup notes, and reviewer account or Atlassian test-site access.
  • Privacy and Security tab, partner verification, security vulnerability posture, and cloud app security requirement evidence.
  • Atlassian Marketplace approval before public-readiness claims.

Explicit Non-Goals

  • No public Atlassian Marketplace claim until the Forge Jira scaffold is promoted into a deployed app and Atlassian review passes.
  • No unmanaged direct Jira writes from the Marketplace app.
  • No broad Jira admin scopes, site-wide reads, customer exports, attachment reads, or user-directory access unless the exact v1 capability requires them and the implementation is validated end to end.
  • No packaged Jira knowledge sync claim until an authenticated, tenant-scoped, auditable sync path exists and is reviewed.
  • No customer-data screenshots, raw Jira exports, Atlassian event dumps, or private tenant payloads in Marketplace screenshots or review evidence.
  • No positioning as a generic “AI agent executes any Jira action” app. Public copy must stay anchored to WorkItem creation/linking, setup, and governed review.

Review Gates

Implemented:

  • Public API action types include jira_create_issue and jira_update_issue.
  • Public BFF mapping code converts Jira create/update action payloads into governed action requests and proposal views.
  • Shared Marketplace OAuth install path supports Atlassian/Jira 3LO, selected Jira Cloud site discovery, per-site runtime keying, tenant-scoped Secret Manager credentials, and a Jira issue-context runtime binding with jira_create_issue and jira_update_issue action allowlists.
  • Pulumi wires Atlassian OAuth client ID and secret mounts plus redirect URL and least-privilege install scopes into public-bff.
  • Public API docs and generated OpenAPI are published.
  • Private Forge manifest scaffold exists at packages/atlassian-marketplace-app for the Jira issue-panel v1.
  • Public Jira setup/support documentation exists at Atlassian setup and support.
  • The scaffold generates a Forge manifest.yml, normalized manifest JSON, Marketplace listing inputs, and submission-readiness blockers.
  • Scaffold validation enforces read:jira-work, one explicit Threada API backend egress URL, no Jira write/admin/export/attachment/user-directory scopes, reviewable issue-panel behavior flags, production host checks for submission readiness, and no public-readiness claim while placeholder values or review evidence are missing.

Missing:

  • Deployed Forge runtime implementation for the generated issue-panel manifest.
  • Atlassian developer console app, Forge lint/precheck evidence, production deployment, distribution/share path, fresh-site install evidence, and Marketplace listing link.
  • Forge issue-panel UX wired to the runtime Atlassian/Jira OAuth install binding.
  • Tenant/site/project mapping, setup-required, success, approval-pending, and uninstall or disconnect behavior from the reviewed Jira panel flow.
  • Remote-host, Forge invocation token, permission, logging, encryption, tenant-isolation, and incident-response evidence where the app egresses data.
  • Marketplace listing copy, logo/banner/screenshots, test instructions, setup notes, and reviewer access.
  • Privacy and Security tab, partner verification, security workflow evidence, and Atlassian Marketplace approval report.

Blocked:

  • Public Atlassian Marketplace submission is blocked until the first-class Forge Jira scaffold is deployed, runtime behavior is implemented and testable, security and privacy gates pass, and reviewer setup is complete.

Launch Checklist

  1. Keep the v1 Atlassian surface to the committed Forge Jira issue-panel scaffold that creates or links a governed Threada WorkItem.
  2. Rebuild the scaffold with real ATLASSIAN_FORGE_APP_ID, ATLASSIAN_FORGE_ICON_URL, THREADA_API_BASE_URL, and ATLASSIAN_MARKETPLACE_LISTING_KEY, then promote the generated manifest.yml into a deployable Forge app.
  3. Use the deployed Atlassian/Jira OAuth install binding to map the selected Atlassian Cloud ID and Jira site to a Threada tenant, pack, queue, or workspace.
  4. Implement Forge issue-panel setup-required behavior, WorkItem creation/linking, status feedback, and uninstall or disconnect handling.
  5. Wire outbound Jira create/update behavior only through Threada governed action proposals with policy, approval, idempotency, and audit controls.
  6. Run Forge lint/precheck validation, deploy production, enable distribution, link the Forge app to a Marketplace listing, and validate install on a fresh Jira Cloud test site.
  7. Create sanitized screenshots and demo material for the key user flow.
  8. Complete Privacy and Security tab, partner verification, security workflow, scope justification, remote-host explanation, and reviewer credentials.
  9. Submit through Atlassian Marketplace review and resolve all review issues before claiming Marketplace readiness.

Runtime Architecture Recommendation

The long-term integration architecture should stay split by responsibility:

  • deploy-tool marketplace-package owns the shared packaging and launch-control mechanics: descriptor discovery, build/validate commands, readiness evidence contracts, and runtime-binding checks.
  • deploy-tool marketplace-program owns release/program gates.
  • Provider packages own only provider-specific descriptors, manifest/listing emission, scope policy, evidence keys, and schema rules.
  • public-bff owns external OAuth/install edges and Secret Manager credential writes.
  • Runtime services own tenant-scoped integration records, provider adapters, action allowlists, idempotency, audit, and execution.
  • Launch checks run last, after the provider app can be installed, mapped to a tenant, and exercised end to end in runtime code.

Do not merge all marketplace integrations into one generic provider generator. Provider artifacts are structurally different: Forge manifests, Teams app packages, OAuth app listings, Zendesk app files, SaaS marketplace metering, and directory-only SSO submissions all have different review and runtime surfaces. The scalable pattern is shared contracts and gates plus narrow provider-local emitters.

References