---
title: App execution with Airflow
description: Run Cuitty Code Apps through Airflow DAGs and reconcile callbacks.
section: Code
order: 16
updatedAt: 2026-05-24
slug: code/app-execution-airflow
---
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.

## Required services

- Cuitty Git 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

```bash
AIRFLOW_URL=http://localhost:8080
AIRFLOW_USERNAME=airflow
AIRFLOW_PASSWORD=airflow
CUITTY_PUBLIC_URL=http://localhost:4350
CUITTY_APP_EXECUTION_MODE=airflow
CUITTY_APP_RUN_CALLBACK_SECRET=dev-callback-secret
```

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

```bash
CUITTY_APP_EXECUTION_MODE=simulate
```

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

## DAG run payload

Airflow receives a DAG run `conf` payload shaped like this:

```json
{
  "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 `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 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`.

Trigger reconciliation through the API when needed:

```bash
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.

## Related pages

- [Cuitty Code Apps](/docs/code/apps)
- [Code App Market](/docs/code/app-market)
- [Authorization with SpiceDB](/docs/code/authz-spicedb)
- [Operator runbook](/docs/code/operator-runbook)