Use Airlift with Fabric Runway

The two CLIs have one owner each:

The governing rule is: Airlift may block on Runway state; it never re-owns it. Airlift stores a requirement plus verified Runway references and digests. Runway owns the release and environment state machines.

If the customer already uses Databricks

A Databricks-only customer that is not running a migration or modernization engagement does not need Airlift for deployment. Use Runway directly:

fr catalog
fr deploy
fr promote

Use the Runway console or API for detailed deployment state and reconciliation. The current fr CLI does not expose separate status or sync commands; that is a Runway CLI concern, not a reason to create an Airlift estate. Never invent a source estate solely to gain release commands.

If the customer later starts a governed Databricks-to-Databricks modernization program, Airlift can track that program once it has an admitted modernization engagement profile. Runway still owns every release operation.

If Airlift is managing a migration

1. Register the immutable target artifacts

fa artifact register \
  --file deployment-manifest-artifact.json \
  --idempotency-key sales-bundle-manifest-v7

Accepted artifact kinds are target_code, target_configuration, deployment, and deployment_manifest.

2. Declare the required Runway outcome

{
  "engagementId": "eng_01J...",
  "estateId": "est_01J...",
  "waveId": "wav_01J...",
  "operation": "deploy",
  "environment": "staging",
  "artifactIds": ["art_01J...", "art_01K..."],
  "requiredState": "succeeded"
}

fa deployment require \
  --file deployment-requirement.json \
  --idempotency-key sales-staging-v7

require does not execute the deployment. It records what the migration needs, verifies artifact and engagement scope, and computes desiredDigest from the operation, environment, and sorted artifact ID/digest pairs. A production requirement needs a frozen engagement.

The Airlift console calls this Save release requirement. Saving is successful when the requirement appears as Awaiting observation. That status means the desired release is recorded but no verified Runway result is connected yet—not that the button failed.

3. Execute the release in Runway

The release engineer or CI system uses Runway:

fr deploy

Promotion remains a distinct Runway approval operation:

fr promote

The current production adapter is observation-only: fr or Runway CI creates the release. Airlift does not submit a second deployment request.

4. Connect the Runway result

Copy the deployment ID and staged artifact SHA-256 printed by fr deploy. On the Airlift deployment page, enter them under Connect the Runway result, or use the CLI:

{
  "deploymentRequirementId": "dpr_01J...",
  "runwayRequestRef": {
    "system": "runway",
    "type": "deployment",
    "id": "dep_01J...",
    "digest": "<64-character-lowercase-sha256>"
  }
}

fa deployment connect \
  --file runway-reference.json \
  --idempotency-key sales-staging-v7-runway

Connecting the result records a pointer, not proof. A person cannot author Runway truth by typing an ID or digest. Airlift still queries Runway and verifies the deployment before changing migration readiness.

5. Verify the Runway result

The Airlift worker accepts only a narrow Runway observation:

type DeploymentObservation = {
  requestRef: ForeignReference;
  releaseRef?: ForeignReference;
  state: 'pending' | 'running' | 'succeeded' | 'failed' | 'rolled_back' | 'unknown';
  actualDigest?: string;
  observationRef: ForeignReference;
  observationDigest: string;
  detail?: string;
};

Only admitted automation can record or reconcile this observation. Choose Check Runway result now in the Airlift console, or let service automation perform the same check. Configure the observer with AIRLIFT_DEPLOYMENT_ADAPTER=runway, AIRLIFT_RUNWAY_API_URL, and a secret-backed AIRLIFT_RUNWAY_API_TOKEN. Optionally set AIRLIFT_RUNWAY_APP_URL so the console offers an Open Runway link. It verifies organization, environment, terminal state, and Runway artifact digest before recording evidence. Airlift intentionally exposes no deployment sync, observe, or reconciliation CLI verbs because a caller must not author Runway truth.

Use release qualification to bind the resulting Runway observation to the generated Airlift candidate and Experiments verdicts.

6. Inspect migration readiness

fa deployment status dpr_01J... --json
fa deployment list --engagement-id eng_01J... --json

These commands read Airlift's last admitted projection; they do not query Runway live. A pending requirement remains pending until the configured service integration records a verified Runway observation. Investigate the integration or the release in Runway rather than forcing Airlift state from the CLI.

Airlift derives the outcome:

• matched when the observed state equals the required state and any actual digest equals the desired digest;
• drifted when state or digest differs;
• failed when Runway reports failure; and
• uncertain when Runway cannot determine actual state.

The Airlift Deployment requirements screen shows the requirement, both digests, foreign Runway references, and its effect on migration readiness. Use Runway to inspect or act on the release itself.

Rollback ownership

Runway executes release rollback. Airlift may declare that a migration recovery path requires rolled_back, then it observes the resulting Runway reference and preserves the migration evidence ledger. fa never exposes a rollback execution command.