GitHub App Setup

The Specwright GitHub App is the primary integration point. It receives webhooks for pushes, pull requests, and issue comments, enabling automated PR analysis and doc maintenance.

Creating the GitHub App

1. Go to Settings > Developer settings > GitHub Apps > New GitHub App

2. Configure:

   • Name: Specwright (or any name)
   • Homepage URL: Your deployment URL
   • Webhook URL: https://<your-domain>/webhook
   • Webhook secret: Generate a random secret (openssl rand -hex 32)

3. Permissions:

   • Repository Contents: Read & write (code + docs, doc-update PRs)
   • Pull requests: Read & write (doc PRs, comments)
   • Issues: Read & write (generated tickets)
   • Metadata: Read-only
   • Members: Read-only (ownership graph)

4. Events — subscribe to all of these:

   • push
   • pull_request
   • issues
   • issue_comment
   • installation
   • installation_repositories

5. After creation:

   • Note the App ID from the app settings page
   • Generate a private key (PEM file) — download and save it
   • Install the app on your organization/repos

Webhook Events

Event	Actions	What Specwright Does
push	—	Watches for spec and doc changes on the default branch
pull_request	opened, synchronize, reopened, merged, closed	Runs PR analysis, posts spec context comments
issues	created, closed, labeled	Triggers reverse sync (ticket → spec status)
issue_comment	created	Handles @specwright commands (dismiss, reanalyze, apply docs)
installation	created, suspended, deleted	App lifecycle management
installation_repositories	added, removed	Repo onboarding/offboarding

Auth0 Configuration (Optional)

If you want web login, CLI auth, or role-based access control:

1. Create an Auth0 Application (type: Regular Web Application)

   • Allowed Callback URLs: https://<your-domain>/auth/callback
   • Allowed Logout URLs: https://<your-domain>

2. Enable connections (under Authentication > Social / Enterprise):

   • GitHub (social connection) — for developer login
   • Google Workspace (enterprise OIDC) — for org SSO
   • Passwordless email (magic link) — fallback for non-SSO users

3. Enable Device Authorization Grant (under Application Settings > Advanced > Grant Types) — required for specwright login CLI auth

4. Configure refresh token rotation (under Application Settings > Refresh Token Rotation):

   • Rotation: enabled
   • Absolute lifetime: 7 days
   • Reuse interval: 0 (rotate on every use)

Environment Variables

Variable	Required	Description
AUTH0_DOMAIN	Yes (if auth enabled)	Auth0 tenant domain (e.g. your-tenant.auth0.com)
AUTH0_CLIENT_ID	Yes (if auth enabled)	Auth0 application client ID
AUTH0_CLIENT_SECRET	Yes (if auth enabled)	Auth0 application client secret
AUTH0_AUDIENCE	Yes (if auth enabled)	Auth0 API identifier (e.g. https://specwright.yourcompany.com/api). Required for JWT access token validation — without it, Auth0 returns opaque tokens that can't be verified server-side.
AUTH0_DEVICE_CLIENT_ID	No	Separate Native app client ID for CLI device auth. If not set, falls back to AUTH0_CLIENT_ID.

All secrets should be managed via Doppler or K8s secrets — never in config files.

Auth0 API Resource Server

For JWT-based auth (required for CLI login and server-proxied ticket sync), you need an Auth0 API:

1. Go to Auth0 Dashboard > Applications > APIs > Create API
2. Set the Identifier (audience) to your deployment URL + /api (e.g. https://specwright.yourcompany.com/api)
3. Enable RBAC and Add Permissions in the Access Token if you want role-based access control
4. Use this identifier as the AUTH0_AUDIENCE environment variable

Database Tables

Auth requires two additional tables (sessions and org_members). These are created automatically on startup via ensure_schema. If creation fails (e.g., insufficient DB permissions), the server will fail to start — check pod logs for SQL errors.