DAG Versioning and CI/CD

Analogy categoryAnalogies

The Challenge: DAGs Change, but Task History Doesn't

Unlike application code that gets fully redeployed on each release, a DAG's definition can change while past DagRuns referencing the old task structure still exist in the metadata database — if you rename or remove a task that already has historical TaskInstance records, those old runs' Grid view can show orphaned or missing entries. Airflow 2.9+ introduced DAG Versioning, which snapshots a DAG's structure (dag_hash, serialized in the serialized_dag table) at each parse, so the Grid view can render a historical run against the DAG structure that was actually active when that run executed, rather than the current structure.

🏏

Cricket analogy: It's like a team changing its playing eleven and batting order mid-season, but the scorecards from earlier matches still need to correctly show who actually batted at number four that day, not whoever bats there now.

GitOps: DAG Deployment via CI/CD Pipeline

The standard production pattern treats the DAGs folder as a build artifact of a Git repository: a CI pipeline (GitHub Actions, GitLab CI, Jenkins) runs on every pull request to lint the code, run the DagBag import-error test and any structural/unit tests, and only on merge to the main branch does a deployment step sync the validated DAGs to the Airflow environment — either via a git-sync sidecar polling the repo, or by baking DAGs into a new container image and rolling it out. This ensures a bad DAG never reaches a live scheduler because CI acts as a gate before any human or automated process ever pushes code where the scheduler can pick it up.

🏏

Cricket analogy: It's like a franchise requiring every new player signing to pass fitness and skill assessments before ever being added to the official squad list, so an unfit player never takes the field in a real match.

yaml

# .github/workflows/airflow-ci.yml
name: Airflow DAG CI
on:
  pull_request:
    paths: ["dags/**"]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.11" }
      - run: pip install -r requirements.txt
      - run: pytest tests/dags/ -v
      - name: Lint DAG files
        run: python -m pyflakes dags/

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Sync DAGs to S3 (picked up by git-sync / bucket-sync sidecar)
        run: aws s3 sync dags/ s3://my-airflow-dags/prod --delete

Rollback Strategy

Because DAGs are just files synced from Git, rolling back a bad deployment is a Git revert followed by the same CI/CD pipeline redeploying the previous known-good commit — there's no special Airflow-specific rollback mechanism, which is precisely the benefit of treating DAG code as a normal build artifact. What CI/CD does not roll back automatically is state already changed by a bad run (a partial table write, a sent notification); those side effects need idempotent task design or a compensating cleanup task so a rollback of code doesn't leave inconsistent downstream data.

🏏

Cricket analogy: It's like a team reverting to last season's tactical playbook after a new strategy backfires in a match — the playbook itself reverts cleanly, but any runs already scored under the bad tactic can't be undone, only accounted for going forward.

Design tasks to be idempotent (safe to re-run with the same result) wherever possible — e.g., INSERT ... ON CONFLICT upserts instead of blind INSERTs — so that a rollback followed by a rerun of affected DAG runs produces correct data without manual cleanup.

Pitfall: Treating `dags/` as Mutable Shared State

A dangerous anti-pattern is editing DAG files directly on a production scheduler's filesystem or shared volume (SSH in and vim a file) instead of going through the CI/CD pipeline — this bypasses every test gate, leaves no audit trail of who changed what and why, and creates drift between what's in Git (the supposed source of truth) and what's actually running. Enforcing that the production DAGs folder is read-only except for the automated sync process (git-sync or the deploy step) is the single most effective control against this.

🏏

Cricket analogy: It's like a player quietly swapping their own bat mid-match without going through the official equipment check that every other bat passes — it might work fine, but if it doesn't, there's no record of what changed or why, and nobody else can reproduce the fix.

Never edit DAG files directly on a production scheduler's filesystem. Make the production DAGs location read-only to humans (writable only by the automated CI/CD sync process) so Git remains the single source of truth, every change is tested and auditable, and DAG versioning history stays accurate.

Airflow 2.9+ DAG Versioning snapshots DAG structure per parse (dag_hash) so historical runs render against the DAG structure active when they executed, not the current one.
GitOps is the standard pattern: CI tests every PR (DagBag import test, structural/unit tests, lint) and only merges to main trigger deployment to the live environment.
Deployment typically syncs DAGs via git-sync sidecar or bakes them into a new container image, gated entirely by the CI pipeline passing.
Rollback is a Git revert plus redeploy of the previous commit — there is no special Airflow rollback mechanism beyond normal version control.
Idempotent task design (upserts, not blind inserts) is essential so a code rollback followed by a rerun produces correct data without manual cleanup.
Never edit DAG files directly on a production scheduler's filesystem — it bypasses tests, breaks the audit trail, and causes drift from Git as source of truth.
Make the production DAGs location read-only except to the automated CI/CD sync process.