Skip to main content
Private beta

App execution with Airflow

Run Cuitty Code Apps through Airflow DAGs and reconcile callbacks.

HTML Markdown JSON

Production Code App runs are submitted to Airflow. Cuitty Code owns app metadata, installs, grants, and run state; Airflow owns task orchestration and execution logs.

Required services

  • Cuitty Code API and database.
  • Airflow webserver and scheduler.
  • Cuitty Auth for actor identity.
  • SpiceDB for app install, run, and log-view permissions.
  • Optional object storage for app logs and execution artifacts.

Environment variables

Production deployments should keep Airflow credentials and callback signing material behind Safe references:

AIRFLOW_URL=https://airflow.example.com
AIRFLOW_USERNAME=airflow-service
AIRFLOW_PASSWORD=cuitty-safe:acme/prod/airflow-password
CUITTY_PUBLIC_URL=https://code.example.com
CUITTY_APP_EXECUTION_MODE=airflow
CUITTY_APP_RUN_CALLBACK_SECRET=cuitty-safe:acme/prod/app-run-callback-secret

For an isolated local development Airflow only, use disposable placeholder values:

AIRFLOW_URL=http://localhost:8080
AIRFLOW_USERNAME=airflow
AIRFLOW_PASSWORD=<local-dev-only-airflow-password>
CUITTY_PUBLIC_URL=http://localhost:4350
CUITTY_APP_EXECUTION_MODE=airflow
CUITTY_APP_RUN_CALLBACK_SECRET=<local-dev-only-callback-secret>

For local development without a live Airflow deployment, use simulation mode:

CUITTY_APP_EXECUTION_MODE=simulate

When the auth issuer or Airflow URL points at local test hosts, Cuitty Code may also simulate Airflow automatically.

DAG run payload

Airflow receives a DAG run conf payload shaped like this:

{
  "run_id": "app-run-uuid",
  "run_kind": "manual",
  "app_id": "app-uuid",
  "app_version_id": "app-version-uuid",
  "installation_id": "install-uuid",
  "actor_user_id": "user-uuid",
  "owner": { "kind": "org", "slug": "acme" },
  "input": { "event_target": "airflow:deploy_guard.pr_opened" },
  "callback": {
    "url": "http://localhost:4350/api/v1/apps/runs/app-run-uuid/callback",
    "hmac_header": "x-cuitty-signature",
    "timestamp_header": "x-cuitty-timestamp"
  }
}

The DAG ID can be provided in run input as airflow_dag_id, derived from an event_target that starts with airflow:, or derived from the app and run kind.

Callback signing rules

Airflow should call the callback URL when a run changes state. The request must include:

  • x-cuitty-timestamp as a Unix timestamp.
  • x-cuitty-signature as an HMAC SHA-256 signature.
  • A body containing the Cuitty app run ID, Airflow DAG ID, Airflow run ID, state, optional log URL, and optional error message.

The signature is computed over timestamp.body with the resolved value from CUITTY_APP_RUN_CALLBACK_SECRET. Timestamps outside the accepted skew window are rejected, and terminal callbacks should be idempotent.

Reconciliation behavior

Callbacks are not the only source of truth. Cuitty Code should reconcile submitted and running app runs by polling Airflow for DAG run state. Missed callbacks, transient API failures, and worker restarts should eventually converge to succeeded, failed, or canceled.

Trigger reconciliation through the API when needed:

curl -X POST http://localhost:4351/api/v1/apps/runs/reconcile   -H "Authorization: Bearer $CUITTY_TOKEN"

Permissions model

Users must be allowed to view the app installation to see run state. Managing, running, canceling, or configuring app runs requires installation-level permissions. Airflow log URLs should be displayed only when the current user can view the run and the Airflow deployment exposes the log securely.

Failure modes and recovery

  • DAG submission fails: record the error and leave the app run failed or retryable.
  • API accepts a run but loses the Airflow response: reconciliation should find the deterministic DAG run or fail after timeout.
  • Callback signature fails: reject the callback, check the shared secret, and rely on reconciliation.
  • Run stuck in submitted or running: poll Airflow, inspect task logs, and force reconciliation.
  • Cancellation requested: map to Airflow cancellation when supported, otherwise keep local state cancel-requested until reconciliation completes.