Fundamentals Tutorial
Purpose and Scope
The Fundamentals tutorial is the first guided path for understanding how Apache Airflow turns Python code into scheduled, observable workflows. It is aimed at a reader who has already reached a running Airflow environment through the Quick Start and now needs to understand the mental model behind a DAG, a task, an operator, dependencies, schedules, time zones, templates, and basic testing. The official tutorial presents this as “Airflow 101: Building Your First Workflow,” then walks from a simple workflow definition to validation and task execution checks before pointing readers toward TaskFlow, pipeline, object-storage, and human-in-the-loop tutorials.
This page documents the tutorial as a developer-facing learning flow rather than as an exhaustive API reference. A DAG, or directed acyclic graph, is the workflow definition: it describes what work exists and how tasks depend on one another. A task is one node of that graph, usually produced by an operator or a decorated Python function in later tutorials. A DAG run is a scheduled or manually triggered execution of that graph for a logical date. Understanding those terms early helps readers interpret both the Python file and the Airflow UI views that show task state over time.
Sources: docs/images/documentation_architecture.py, .apache-magpie-overrides/README.md
Relevant Source Files
docs/images/documentation_architecture.py- Generates the documentation architecture diagram for the Airflow project, showing how package documentation is published from Airflow-related repositories through release-manager and committer actions to the live documentation site..apache-magpie-overrides/README.md- Defines the repository-local override area used by agentic framework skills and states the rule that local adopter-specific changes live in this directory rather than in the framework snapshot..apache-magpie-overrides/pr-management-config.md- Supplies Apache Airflow values for PR triage automation, including project identifiers, labels, grace windows, and feedback delivery behavior..apache-magpie-overrides/pr-management-triage-ci-check-map.md- Maps Airflow CI check-name patterns to user-facing categories and documentation links such as static checks, unit tests, documentation builds, Helm tests, Kubernetes tests, image builds, and provider tests..apache-magpie-overrides/pr-management-triage-comment-templates.md- Provides Airflow-specific URLs and wording used when PR triage automation comments on quality criteria, static checks, tests, documentation builds, provider testing, and project communication.
Sources: docs/images/documentation_architecture.py, .apache-magpie-overrides/README.md, .apache-magpie-overrides/pr-management-config.md, .apache-magpie-overrides/pr-management-triage-ci-check-map.md, .apache-magpie-overrides/pr-management-triage-comment-templates.md
Core Primitives
The tutorial’s first job is to make the Airflow primitives concrete. A DAG file is ordinary Python code imported by Airflow, so the beginning of the walkthrough emphasizes imports, default arguments, and creating a DAG object. Operators define what kind of work a task performs, while task instances are the runtime records created when a task is scheduled inside a DAG run. Dependencies connect tasks into the graph, and Airflow uses those edges to decide which tasks can run, wait, retry, or fail. This is why the tutorial spends time on both the file structure and the graph semantics.
Templating is introduced because many workflows need runtime values such as dates, identifiers, or paths. Airflow uses Jinja templating in supported operator fields so a static DAG definition can still adapt to a particular run. The tutorial also introduces documentation attached to DAGs and tasks, because workflow code is read in two places: in source control by developers and in the UI by operators. Good inline documentation makes the graph understandable during failures, reviews, and handoffs, especially when the workflow contains business-specific transformations.
Time is another core primitive in Airflow, not just an incidental parameter. The official fundamentals sequence calls out working with time zones because schedules, logical dates, and data intervals are easier to reason about when every task in a DAG follows a clear time convention. New users should treat time zone choices as part of the workflow contract. If a pipeline processes daily data, the DAG definition, templates, and tests should all make the intended logical date behavior explicit before the workflow is promoted into shared environments.
Tutorial Execution Flow
A practical way to follow the fundamentals tutorial is to read it as a lifecycle. First, write the DAG definition file with imports, default arguments, the DAG declaration, and tasks. Second, define dependencies so Airflow can compute a valid execution order. Third, add templates and documentation where runtime substitution or operator guidance is needed. Fourth, validate the DAG from the command line before relying on the scheduler. Finally, test individual task instances and DAG runs so the graph is not only syntactically loadable but also operationally understandable.
The official tutorial includes command-line metadata validation and testing of task instances and DAG runs. In practice, this means checking that Airflow can import the file, list the DAG, and execute targeted pieces without waiting for the full scheduler loop. Typical early checks include listing DAGs, inspecting tasks, and running a single task for a chosen logical date. These commands are not a substitute for production monitoring, but they shorten the feedback cycle while the learner is still connecting Python code, graph structure, and runtime behavior.
# Examples of the kind of local checks the fundamentals tutorial prepares you to run.
airflow dags list
airflow tasks list <dag_id>
airflow tasks test <dag_id> <task_id> <logical_date>The tutorial sequence deliberately points next to more specialized tutorials. After the fundamentals path, TaskFlow shows a more Pythonic authoring style where functions become tasks, the pipeline tutorial focuses on a complete data workflow, the object-storage tutorial introduces cloud-native file patterns, and the HITL tutorial covers human review and approval workflows. That ordering matters: the fundamentals page gives the vocabulary needed to understand why those later tutorials introduce new APIs or integrations rather than replacing the underlying Airflow execution model.
System-to-Code Mapping
The requested repository files for this page do not implement tutorial tasks, but they do explain how the tutorial reaches readers and how changes around it are managed. docs/images/documentation_architecture.py builds a diagram containing Airflow GitHub repositories, release-manager and committer roles, the live documentation bucket, CloudFront, and the public Airflow website. That matters for a tutorial page because the published documentation is a release artifact, not merely a local markdown file. The fundamentals guide belongs to the same documentation delivery system that serves versioned Airflow docs to users.
The .apache-magpie-overrides files describe repository-local behavior for PR management automation. The README establishes that overrides are scoped to this adopter repository and should not be made by editing the framework snapshot. The configuration file sets Airflow-specific identifiers such as the committers team, area-label prefix, review labels, and stale-work thresholds. Together, these files show that tutorial-quality changes move through an Airflow-specific contributor workflow with predictable labeling and feedback mechanisms rather than through ad hoc review conventions.
Sources: .apache-magpie-overrides/README.md, .apache-magpie-overrides/pr-management-config.md
Testing and Documentation Signals
For contributors changing tutorial material, the CI-check map is the most concrete signal in the supplied source. It categorizes checks for static analysis, Ruff, mypy, unit tests, documentation builds, Helm tests, Kubernetes tests, image builds, provider tests, and a catch-all category. Documentation changes are explicitly mapped through docs, spellcheck-docs, and build-docs patterns to the documentation-building guide. That means a fundamentals tutorial update should be treated as a tested documentation change: spelling, generated docs, and surrounding examples need to remain healthy before the change is ready for review.
The comment-template overrides reinforce the same expectation from the contributor side. They define Airflow-specific links for pull-request quality criteria, static checks, testing, documentation building, Helm tests, Kubernetes tests, provider testing, and project communication. If a tutorial PR fails checks, the automation can point the contributor to the right kind of fix rather than only reporting a red build. For new documentation contributors, this is part of the learning loop: the tutorial teaches Airflow concepts, while the project’s review automation teaches how to keep the tutorial reliable as the codebase changes.
Sources: .apache-magpie-overrides/pr-management-triage-ci-check-map.md, .apache-magpie-overrides/pr-management-triage-comment-templates.md
Next Steps
After completing the Fundamentals tutorial, use the DAG, task, dependency, templating, and testing vocabulary to decide where to go next. If you prefer Python functions and typed data passing, continue to the TaskFlow tutorial. If you want a complete data workflow, continue to the pipeline tutorial. If your workflows depend on files in object storage, continue to the object-storage tutorial. If your process requires manual approval, review, or option selection, continue to the human-in-the-loop tutorial. For operational depth, read the DAGs, tasks/operators/hooks, scheduling, and task logs pages after the tutorials.