Bundles¶

Use the GitDagBundle to configure a Git bundle in your Airflow’s [dag_processor] dag_bundle_config_list.

Example of using the GitDagBundle:

JSON format example:

export AIRFLOW__DAG_PROCESSOR__DAG_BUNDLE_CONFIG_LIST='[
 {
     "name": "my-git-repo",
     "classpath": "airflow.providers.git.bundles.git.GitDagBundle",
     "kwargs": {
         "subdir": "dags",
         "tracking_ref": "main",
         "refresh_interval": 3600,
         "submodules": false,
         "prune_dotgit_folder": true,
         "sparse_dirs": ["dags", "includes"]
     }
 }
]'

tracking_ref accepts a branch, tag, or full commit SHA. Setting it to a commit SHA pins the bundle to that exact commit:

export AIRFLOW__DAG_PROCESSOR__DAG_BUNDLE_CONFIG_LIST='[
 {
     "name": "my-git-repo",
     "classpath": "airflow.providers.git.bundles.git.GitDagBundle",
     "kwargs": {
         "repo_url": "https://github.com/org/repo.git",
         "tracking_ref": "a3d1850dd1aa1919a61620aa39f202185c9321c0",
         "subdir": "dags"
     }
 }
]'

Branches move as new commits are pushed, so combined with refresh_interval they pick up new code without a restart. Tags and commit SHAs are static (assuming tags aren’t moved), pinning the bundle to known-good code — but changing a SHA-pinned tracking_ref is a dag_bundle_config_list config change, not a ref move, so it only takes effect once the Dag processor is restarted and reloads the configuration. If [dag_processor] disable_bundle_versioning (or the disable_bundle_versioning Dag parameter) is set, workers also resolve code from their own tracking_ref rather than a recorded bundle version, so they need the updated configuration too.

Note

Rolling back a SHA-pinned tracking_ref after a restart is reliable, since the commit’s objects are already present in the bundle’s local storage. Promoting to a new SHA can fail to check out that commit unless the bundle’s local storage is cleared first (for example, a fresh pod, or manually deleting the bundle’s directory) — see GH-71388 for the underlying limitation.