{ "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 Git owns app metadata, installs, grants, and run state; Airflow owns task orchestration and execution logs.\n\n## Required services\n\n- Cuitty Git 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\n```bash\nAIRFLOW_URL=http://localhost:8080\nAIRFLOW_USERNAME=airflow\nAIRFLOW_PASSWORD=airflow\nCUITTY_PUBLIC_URL=http://localhost:4350\nCUITTY_APP_EXECUTION_MODE=airflow\nCUITTY_APP_RUN_CALLBACK_SECRET=dev-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 Git 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 `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 Git 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)", "body_html": "

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

\n

Required services

\n\n

Environment variables

\n
AIRFLOW_URL=http://localhost:8080\nAIRFLOW_USERNAME=airflow\nAIRFLOW_PASSWORD=airflow\nCUITTY_PUBLIC_URL=http://localhost:4350\nCUITTY_APP_EXECUTION_MODE=airflow\nCUITTY_APP_RUN_CALLBACK_SECRET=dev-callback-secret
\n

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

\n
CUITTY_APP_EXECUTION_MODE=simulate
\n

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

\n

DAG run payload

\n

Airflow receives a DAG run conf payload shaped like this:

\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

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.

\n

Callback signing rules

\n

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

\n\n

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

\n

Reconciliation behavior

\n

Callbacks are not the only source of truth. Cuitty Git 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

Trigger reconciliation through the API when needed:

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

Permissions model

\n

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.

\n

Failure modes and recovery

\n\n

Related pages

\n", "links_out": [ "/docs/code/apps", "/docs/code/app-market", "/docs/code/authz-spicedb", "/docs/code/operator-runbook" ] }