AHENA
Documentation menu

Guides

CI/CD

Uses the Ahena CLI (beta). Install it with npm install -g @ahena/cli, or prefix commands with npx @ahena/cli. See Installation. The dashboard covers projects, connections, Doctor, the Stack Graph, plans and approvals without it.

ahena deploy-check --environment production

Runs Doctor for one environment (plus repository checks and drift against ahena.lock) and exits 1 when it isn't ready to deploy. Each blocker is labelled with a category:

Category Typical cause
missing production secret STRIPE_WEBHOOK_SECRET (or another secret the app needs) isn't stored
invalid provider credentials A key was revoked, expired or lacks permissions
configuration drift A high-severity value changed outside Ahena since ahena.lock
missing migration supabase/migrations has files the database hasn't applied
broken webhook Endpoint missing, disabled, or accepting unsigned requests
development credential in production Test-mode key configured in production
missing OAuth callback Production redirect URL / site URL not allowed
missing provider ahena.config.ts needs a provider that isn't connected

Warnings (including medium/low drift) don't fail the build unless you pass --strict. --json prints a machine-readable result.

GitHub Actions

ahena ci init                                   # writes .github/workflows/ahena-deploy-check.yml
ahena ci token create --raw | gh secret set AHENA_TOKEN
ahena lock && git add ahena.lock                # so CI checks drift too

Inside GitHub Actions, deploy-check writes ::error / ::warning annotations and a job summary table ($GITHUB_STEP_SUMMARY). Use --format text to turn that off.

The generated workflow runs npx @ahena/cli@<version> deploy-check with permissions: contents: read, pinned to the CLI version that wrote it. Only Ahena can publish in the @ahena scope, so nothing else can take its place.

CI tokens

ahena ci token create makes a token for one project that:

  • only reads and runs checks: the API accepts it on an explicit allowlist of routes (project, connections, secret names, Doctor, provider state). Everything else returns 403.
  • is capped at viewer in core, whatever the creator's role, and sees only its project. Other projects in the organization return 404.
  • expires (default 90 days, maximum 365), can be revoked (ahena ci token revoke <id>), and stops working if its creator loses access to the project.
  • is stored as a SHA-256 hash and shown once. ahena ci token list shows labels, expiry and last use. Requests made with it are audited as via: ci.

Creating or revoking one needs project.update (developer or above).