{
  "slug": "code/app-execution-airflow",
  "title": "App execution with Airflow",
  "description": "Run Cuitty Code Apps through Airflow DAGs and reconcile callbacks.",
  "url": "https://cuitty.com/docs/code/app-execution-airflow",
  "markdown_url": "https://cuitty.com/docs/code/app-execution-airflow.md",
  "json_url": "https://cuitty.com/docs/code/app-execution-airflow.json",
  "frontmatter": {
    "title": "App execution with Airflow",
    "description": "Run Cuitty Code Apps through Airflow DAGs and reconcile callbacks.",
    "order": 16,
    "section": "Code",
    "updatedAt": "2026-05-24"
  },
  "headings": [
    {
      "depth": 2,
      "slug": "required-services",
      "text": "Required services"
    },
    {
      "depth": 2,
      "slug": "environment-variables",
      "text": "Environment variables"
    },
    {
      "depth": 2,
      "slug": "dag-run-payload",
      "text": "DAG run payload"
    },
    {
      "depth": 2,
      "slug": "callback-signing-rules",
      "text": "Callback signing rules"
    },
    {
      "depth": 2,
      "slug": "reconciliation-behavior",
      "text": "Reconciliation behavior"
    },
    {
      "depth": 2,
      "slug": "permissions-model",
      "text": "Permissions model"
    },
    {
      "depth": 2,
      "slug": "failure-modes-and-recovery",
      "text": "Failure modes and recovery"
    },
    {
      "depth": 2,
      "slug": "related-pages",
      "text": "Related pages"
    }
  ],
  "body_markdown": "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.\n\n## Required services\n\n- Cuitty Code API and database.\n- Airflow webserver and scheduler.\n- Cuitty Auth for actor identity.\n- SpiceDB for app install, run, and log-view permissions.\n- Optional object storage for app logs and execution artifacts.\n\n## Environment variables\n\nProduction deployments should keep Airflow credentials and callback signing material behind Safe references:\n\n```dotenv\nAIRFLOW_URL=https://airflow.example.com\nAIRFLOW_USERNAME=airflow-service\nAIRFLOW_PASSWORD=cuitty-safe:acme/prod/airflow-password\nCUITTY_PUBLIC_URL=https://code.example.com\nCUITTY_APP_EXECUTION_MODE=airflow\nCUITTY_APP_RUN_CALLBACK_SECRET=cuitty-safe:acme/prod/app-run-callback-secret\n```\n\nFor an isolated local development Airflow only, use disposable placeholder values:\n\n```dotenv\nAIRFLOW_URL=http://localhost:8080\nAIRFLOW_USERNAME=airflow\nAIRFLOW_PASSWORD=<local-dev-only-airflow-password>\nCUITTY_PUBLIC_URL=http://localhost:4350\nCUITTY_APP_EXECUTION_MODE=airflow\nCUITTY_APP_RUN_CALLBACK_SECRET=<local-dev-only-callback-secret>\n```\n\nFor local development without a live Airflow deployment, use simulation mode:\n\n```bash\nCUITTY_APP_EXECUTION_MODE=simulate\n```\n\nWhen the auth issuer or Airflow URL points at local test hosts, Cuitty Code may also simulate Airflow automatically.\n\n## DAG run payload\n\nAirflow receives a DAG run `conf` payload shaped like this:\n\n```json\n{\n  \"run_id\": \"app-run-uuid\",\n  \"run_kind\": \"manual\",\n  \"app_id\": \"app-uuid\",\n  \"app_version_id\": \"app-version-uuid\",\n  \"installation_id\": \"install-uuid\",\n  \"actor_user_id\": \"user-uuid\",\n  \"owner\": { \"kind\": \"org\", \"slug\": \"acme\" },\n  \"input\": { \"event_target\": \"airflow:deploy_guard.pr_opened\" },\n  \"callback\": {\n    \"url\": \"http://localhost:4350/api/v1/apps/runs/app-run-uuid/callback\",\n    \"hmac_header\": \"x-cuitty-signature\",\n    \"timestamp_header\": \"x-cuitty-timestamp\"\n  }\n}\n```\n\nThe 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.\n\n## Callback signing rules\n\nAirflow should call the callback URL when a run changes state. The request must include:\n\n- `x-cuitty-timestamp` as a Unix timestamp.\n- `x-cuitty-signature` as an HMAC SHA-256 signature.\n- A body containing the Cuitty app run ID, Airflow DAG ID, Airflow run ID, state, optional log URL, and optional error message.\n\nThe 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.\n\n## Reconciliation behavior\n\nCallbacks 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`.\n\nTrigger reconciliation through the API when needed:\n\n```bash\ncurl -X POST http://localhost:4351/api/v1/apps/runs/reconcile   -H \"Authorization: Bearer $CUITTY_TOKEN\"\n```\n\n## Permissions model\n\nUsers 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.\n\n## Failure modes and recovery\n\n- DAG submission fails: record the error and leave the app run failed or retryable.\n- API accepts a run but loses the Airflow response: reconciliation should find the deterministic DAG run or fail after timeout.\n- Callback signature fails: reject the callback, check the shared secret, and rely on reconciliation.\n- Run stuck in `submitted` or `running`: poll Airflow, inspect task logs, and force reconciliation.\n- Cancellation requested: map to Airflow cancellation when supported, otherwise keep local state cancel-requested until reconciliation completes.\n\n## Related pages\n\n- [Cuitty Code Apps](/docs/code/apps)\n- [Code App Market](/docs/code/app-market)\n- [Authorization with SpiceDB](/docs/code/authz-spicedb)\n- [Operator runbook](/docs/code/operator-runbook)",
  "links_out": [
    "/docs/code/apps",
    "/docs/code/app-market",
    "/docs/code/authz-spicedb",
    "/docs/code/operator-runbook"
  ]
}