airflow-hitl_skill

Overview

This skill provides human-in-the-loop (HITL) operators for Apache Airflow 3.1+ to implement approval gates, form inputs, and human-driven branching inside DAGs. Use the provided operators to pause execution until a human responds via the Airflow UI or the REST API. Operators are deferrable so they free worker slots while waiting.

How this skill works

The skill exposes four deferrable operators: ApprovalOperator, HITLOperator, HITLBranchOperator, and HITLEntryOperator. Each operator creates a pending action visible in Airflow’s Browse → Required Actions or via the REST API; execution resumes when a human submits a response, and results are returned via the operator output XCom. Operators support templated markdown bodies, defaults/timeouts, notifiers, respondent restrictions, and standard Airflow callbacks.

When to use it

• Add an explicit human approval or reject gate in a DAG
• Collect structured input or form data from an operator or stakeholder
• Let a human choose downstream branches or multiple downstream tasks to run
• Integrate external responders (Slack, custom app) to approve or submit HITL responses
• Require deferrable, resource-efficient waiting for human input in production workflows

Best practices

• Ensure Airflow version is 3.1+; HITL operators are not available in 2.x
• Prefer deferrable HITL operators instead of custom sensors or polling loops to free worker slots
• For HITLBranchOperator, make options either exact downstream task IDs or use options_mapping to map labels to task IDs
• Define defaults that exist in options if you expect auto-selection on timeout; without defaults the task will fail on timeout
• Use notifiers to surface action links and restrict respondents according to your auth manager format (username, email, or Astro ID)

Example use cases

• ApprovalOperator as a quarterly report gate where Reject skips downstream processing
• HITLOperator to select a payment method and capture numeric params like amount
• HITLBranchOperator to let an operator select which departments’ processing tasks should run
• HITLEntryOperator to collect free-text responses or structured form fields before continuing a workflow
• External integration that polls the HITL REST API and patches choices from Slack or a custom dashboard