Integrations

Defiant integrates with the tools you already use. Most integrations are configured once during defiant init and then used automatically by the relevant agents.

GitHub

Repo access, PR creation, status checks, Actions triggers. Required.

Asana

Task creation and completion via the Scribe agent. Optional.

Sentry

Runtime error capture and triage via the Medic agent. Optional.

PostHog

Usage analytics and feature flags. Optional.

Resend

Transactional email. Optional.

Stripe

Billing and payments for Marketplace/Fintech projects. Optional.

GitHub

Required. GitHub is the source of truth for code and the deployment trigger.

Permissions required

Scope	Why
`repo`	Read/write access to repositories — Builder needs to push branches and open PRs
`workflow`	Trigger GitHub Actions workflows — Launcher uses this to start deploys
`read:org`	Read organization membership — used to scope access to org repos

Setup

defiant config set GITHUB_TOKEN ghp_...

Or during defiant init.

How it’s used

Agent	GitHub action
Builder	Push branch, open PR
Reviewer	Read PR diff, add review comments, approve, merge
Guardian	Read PR diff, add security review comments
Launcher	Trigger workflow dispatch, create version tags
Scribe	Add PR release notes, draft GitHub Releases

Branch strategy

Each Builder task gets its own branch: defiant/<sprint-id>/<task-id>. PRs target the project’s default branch (usually main). The Conductor never force-pushes.

Required repository settings

For the Reviewer to auto-merge PRs:

Enable “Allow auto-merge” in repository settings
Set the required status checks (Defiant adds a defiant/mandate-check status)
Set branch protection: require the defiant/mandate-check status to pass

Asana

Optional. The Scribe agent creates and updates Asana tasks when a sprint completes.

Setup

defiant config set ASANA_PAT 1/...
defiant config set ASANA_PROJECT_GID 1214516646043430

How it’s used

The Scribe agent:

Queries the Asana project for the relevant section
Creates a task for the completed sprint (if one doesn’t exist)
Marks it complete with a note including the sprint ID and PR links

Asana task format

Task name: [Sprint] <sprint goal summary>
Notes:
  Sprint ID: spr_01hw...
  State: COMPLETE
  PRs merged: #42, #43
  Completed: 2026-05-05T14:38:22Z
  Tokens used: 182,304
  Agents: captain, architect, builder (x2), reviewer, guardian, scribe

Custom task mapping

You can map sprint goals to existing Asana tasks by including the Asana GID in the sprint goal:

defiant sprint create \
  --project proj_01hw... \
  --goal "Add profile page [asana:1214516646043430]"

The Scribe will update that specific task rather than creating a new one.

Sentry

Optional. Enables the Medic agent to triage runtime errors automatically.

Setup

defiant config set SENTRY_DSN https://xxx@o123.ingest.sentry.io/456
defiant config set SENTRY_AUTH_TOKEN sntrys_...  # for API access
defiant config set SENTRY_ORG yourorg
defiant config set SENTRY_PROJECT your-project

How it’s used

Error triage on demand:

defiant medic triage --sentry --limit 10

The Medic fetches the 10 most recent unresolved Sentry issues, analyzes each one against the codebase, and produces a diagnosis with a likely root cause and suggested fix.

Auto-triage (optional): Configure a Sentry webhook to POST to the Defiant webhook endpoint, and the Medic will triage new issues automatically:

// Sentry webhook → Defiant
{
  "url": "https://xxx.supabase.co/functions/v1/defiant/webhooks/sentry",
  "events": ["issue"]
}

Sentry release integration

The Launcher automatically creates Sentry releases when it tags a version:

// Created by Launcher after successful deploy
await sentry.releases.create({
  version: 'v2.1.0',
  projects: ['your-project'],
  refs: [{ repository: 'yourorg/my-app', commit: 'abc123' }],
});

PostHog

Optional. Usage analytics and feature flags.

Setup

defiant config set POSTHOG_KEY phc_...
defiant config set POSTHOG_HOST https://app.posthog.com  # or self-hosted URL

How it’s used

Defiant tracks sprint-level analytics:

Event	When
`sprint_created`	Sprint created
`sprint_complete`	Sprint reaches COMPLETE
`sprint_failed`	Sprint reaches FAILED
`mandate_violated`	A mandate violation is found
`inbox_resolved`	An inbox item is resolved

All events include project vertical, agent set, and token usage. No code or goal text is sent.

Feature flags: Defiant checks PostHog feature flags for beta features. To opt into a beta:

defiant config set POSTHOG_DISTINCT_ID your-user-id

Resend

Optional. Transactional email. Used by the Launcher to send deploy notifications and by the Medic to send failure alerts.

Setup

defiant config set RESEND_API_KEY re_...
defiant config set RESEND_FROM "Defiant <noreply@yourdomain.com>"
defiant config set RESEND_NOTIFY_EMAIL "you@yourdomain.com"

Notifications sent

Event	Recipient
Sprint complete	`RESEND_NOTIFY_EMAIL`
Sprint failed	`RESEND_NOTIFY_EMAIL`
Critical inbox item	`RESEND_NOTIFY_EMAIL`
Deploy rollback triggered	`RESEND_NOTIFY_EMAIL`

Configure which notifications to receive:

defiant config set RESEND_NOTIFY_EVENTS "sprint_failed,inbox_critical"

Stripe

Optional. Required for Marketplace and Fintech vertical projects that handle payments.

Setup

defiant config set STRIPE_SECRET_KEY sk_live_...
defiant config set STRIPE_WEBHOOK_SECRET whsec_...

How it’s used

The Ambassador agent uses the Stripe configuration to:

Generate correct Stripe SDK initialization code
Implement webhook signature verification using your webhook secret
Set up Stripe Connect flows for marketplace projects
Validate that payment flows use Stripe (and not raw card handling) per mandate_f1

The Guardian agent uses it to verify that payment-related code routes through Stripe and never stores raw card data.

Test vs. live mode

Defiant detects whether the key is test mode (sk_test_) or live mode (sk_live_) and configures tests accordingly. Builder agents always use test mode in the worktree; live mode is used only by the Launcher for production deploys.

Adding a custom integration

You can extend the Ambassador agent with custom integration knowledge by adding a YAML file to integrations/:

name: My Service
base_url: https://api.myservice.com/v1
auth:
  type: bearer
  env_var: MY_SERVICE_API_KEY

endpoints:
  - name: create_item
    method: POST
    path: /items
    body_schema: { name: string, type: string }
    response_schema: { id: string, created_at: string }

error_codes:
  429: rate_limit
  503: service_unavailable

sdk:
  package: my-service-sdk
  init_pattern: "new MyServiceClient({ apiKey: process.env.MY_SERVICE_API_KEY })"

webhook:
  signature_header: X-My-Service-Signature
  signature_algorithm: HMAC-SHA256
  secret_env_var: MY_SERVICE_WEBHOOK_SECRET

The Ambassador reads this file when the sprint goal or technical plan references My Service and uses it to generate correct initialization and error handling code.