migrating-airflow-2-to-3

SKILL.md

Automated detection and code migration for upgrading Apache Airflow 2.x DAGs to Airflow 3.x.

Provides Ruff-based auto-fix rules (AIR30/AIR301/AIR302/AIR31/AIR311/AIR312) to detect and resolve breaking changes in imports, operators, hooks, and context variables

Covers critical architecture shifts: workers no longer access metadata DB directly; use the Airflow Python client or REST API instead of ORM session queries

Includes manual migration checklist for issues Ruff cannot auto-fix: cron scheduling semantics, .airflowignore glob syntax, OAuth callback URL prefixes, and shared utility imports

Recommends upgrade path: Airflow 2.11 → 3.0.11+ (ideally 3.1) to avoid rollback issues and early 3.0 bugs

Airflow 2 to 3 Migration

This skill helps migrate Airflow 2.x DAG code to Airflow 3.x, focusing on code changes (imports, operators, hooks, context, API usage).

Important: Before migrating to Airflow 3, strongly recommend upgrading to Airflow 2.11 first, then to at least Airflow 3.0.11 (ideally directly to 3.1). Other upgrade paths would make rollbacks impossible. See: https://www.astronomer.io/docs/astro/airflow3/upgrade-af3#upgrade-your-airflow-2-deployment-to-airflow-3. Additionally, early 3.0 versions have many bugs - 3.1 provides a much better experience.

Migration at a Glance