Skip to content
threada Docs

GitHub Marketplace

This guide defines the GitHub Marketplace path for Threada. It is a design and launch-control document, not evidence that a GitHub Marketplace listing has been submitted or approved.

Current Status

GitHub Marketplace is planned. A private launch-control scaffold exists at packages/github-marketplace-app for an organization-owned public GitHub App, read-only app permissions, GitHub App webhooks, Marketplace purchase-webhook posture, listing metadata, setup-guide metadata, reviewer smoke notes, and fail-closed readiness evidence gates.

Submission readiness is intentionally blocked until a real GitHub organization owner, production GitHub App ID, OAuth client ID, Marketplace listing ID, GitHub App private key reference, OAuth client-secret reference, webhook-secret references, install/setup mapping, runtime binding smoke evidence, reviewer-safe smoke evidence, Marketplace submission, and approval tracking exist outside the repo.

Do not submit a public GitHub Marketplace listing until the app is installable in a reviewer-safe organization or repository, the setup URL maps the GitHub installation to a Threada tenant, one v1 workflow works end to end, uninstall cleanup is verified, and sanitized evidence references are captured.

Do not market or claim GitHub Marketplace readiness until GitHub review accepts the listing.

The enterprise-safe first package should be a narrow GitHub App that creates or links a governed Threada WorkItem from GitHub issue, pull request, or discussion context. Start read-only: metadata, issues, pull requests, and discussions. Keep repository contents, organization admin, Actions/workflow, package, secret, code-scanning, check/status, and repository-write permissions out of v1 unless a later reviewed workflow requires them.

GitHub recommends using a separate development app and draft Marketplace listing for testing Marketplace behavior. Keep production test purchases out of the live listing path.

Source Of Truth

The private scaffold source is packages/github-marketplace-app. It renders:

  • github-marketplace-config.json
  • github-app-config.json
  • marketplace-listing.json
  • customer-setup-guide.json
  • assets/README.md
  • reviewer-smoke-test.md
  • readiness.json

Runtime binding is checked through deploy-tool marketplace-package against proto/runtime_automation/runtime_automation.proto. The descriptor binds to INTEGRATION_TYPE_GITHUB; a GitHub listing still cannot be submission-ready without sanitized deployment and smoke evidence for that runtime path.

Review Gates

Implemented:

  • Private GitHub Marketplace launch-control scaffold exists at packages/github-marketplace-app.
  • The scaffold renders GitHub App config, listing metadata, customer setup metadata, reviewer smoke notes, asset checklist, and readiness output.
  • The scaffold enforces read-only v1 GitHub App permissions and rejects broad repository, organization-admin, secret, workflow, package, code-scanning, and billing-runtime claims.
  • Submission readiness requires structured evidence references and a real runtime binding.

Missing:

  • Real organization-owned GitHub App and Marketplace draft listing.
  • Production GitHub App ID, OAuth client ID, callback/setup/webhook URLs, and Secret Manager references.
  • Runtime binding deployment and smoke evidence for INTEGRATION_TYPE_GITHUB.
  • Tenant installation mapping, signed webhook verification, WorkItem linking, setup-required behavior, uninstall cleanup, and reviewer-safe smoke evidence.
  • GitHub Marketplace review submission and approval evidence.

References