@kansodata/openclaw-airflow-dag-git-plugin

Native OpenClaw plugin for controlled Airflow DAG .py operations through a GitHub pull-request workflow.

Scope

What it does

• Reads one allowlisted DAG file from GitHub (airflow_dag_git_read_file).
• Creates or updates one allowlisted DAG file through:

1. branch creation,
2. commit creation,
3. PR opening (airflow_dag_git_open_pr).

What it does not do

• No direct writes to Airflow hosts.
• No auto-merge.
• No direct pushes to protected branches.
• No multi-file edits in V0.
• No delete/rename in V0.
• No CI workflow, secrets, or repo configuration edits.

Why Git/PR instead of direct host writes

The plugin enforces controlled change management with:

• reviewable diffs,
• branch isolation,
• auditable history,
• standard GitHub rollback mechanics.

This reduces operational risk compared to direct host mutation.

Architecture

flowchart LR
  U[User / Agent] --> H[OpenClaw Host]
  H --> P[airflow-dag-git plugin]
  P --> G[GitHub API]
  G --> R[(Target Repository)]
  R --> G
  G --> P
  P --> H

Flow summary: OpenClaw routes the tool call to the plugin, the plugin validates policy and content, and GitHub receives branch/commit/PR operations against the target repository.

Security Model

• Read and PR workflow only.
• No direct writes to Airflow hosts.
• Fail-closed validation on owner/repo/path, file type, and content policy.
• Pull request is the controlled change boundary (no direct protected-branch mutation).

Installation

openclaw plugins install @kansodata/openclaw-airflow-dag-git-plugin

Configuration

Configure under plugins.entries.airflow-dag-git.config.

{
  "plugins": {
    "entries": {
      "airflow-dag-git": {
        "enabled": true,
        "config": {
          "githubToken": "${secret:GITHUB_TOKEN}",
          "allowedOwners": ["kansodata"],
          "allowedRepos": ["airflow-dags"],
          "allowedDagPaths": ["dags/", "airflow/dags/"],
          "defaultBaseBranch": "main",
          "maxFileSizeBytes": 200000,
          "readOnly": false,
          "allowedNetworkHosts": ["internal-api.company.local"]
        }
      }
    }
  }
}

Also supported: GITHUB_TOKEN environment variable fallback.

Tools

airflow_dag_git_read_file

Input:

• owner (string)
• repo (string)
• ref (optional string)
• path (string)

Behavior:

• Validates owner/repo/path against allowlists.
• Requires .py under allowlisted DAG paths.
• Returns content, sha, resolved ref, and size.

airflow_dag_git_open_pr (optional side effects)

Input:

• owner (string)
• repo (string)
• baseBranch (optional string)
• targetPath (string)
• newContent (string)
• commitMessage (string)
• prTitle (string)
• prBody (optional string)
• branchName (optional string)

Behavior (fail-closed):

• Validates owner/repo/path against allowlists.
• Accepts only .py under allowlisted DAG prefixes.
• Rejects traversal and absolute paths.
• Enforces max file size.
• Requires DAG marker (DAG( or @dag).
• Blocks dangerous patterns (subprocess, os.system, eval(, exec().
• Blocks external requests.* unless host is allowlisted.
• Reads current file (if present), creates branch, writes one file, opens PR.
• Returns PR URL, PR number, created branch, commit sha, and short diff summary.

Tool selection guidance

• Use airflow_dag_git_open_pr when proposing a DAG change. This is the primary action path.
• Use airflow_dag_git_read_file only when explicit repository inspection is needed.
• Prefer open_pr for change proposals, because it preserves review and rollback controls.
• Avoid routine pre-reads when the caller already has authoritative DAG content and only needs to propose an update.

Usage example

Example tool call for airflow_dag_git_open_pr:

{
  "owner": "kansodata",
  "repo": "airflow-dags",
  "baseBranch": "main",
  "targetPath": "dags/example_pipeline.py",
  "newContent": "from airflow import DAG\n",
  "commitMessage": "feat(dag): update example pipeline",
  "prTitle": "Update example DAG",
  "prBody": "Proposed via OpenClaw airflow-dag-git plugin."
}

Smoke test evidence

The plugin has been validated end-to-end in a sandbox repository with successful PR creation through airflow_dag_git_open_pr. This confirms the branch, commit, and PR path under the current V0 scope.

V0 limitations

• Single-file change only.
• No delete/rename.
• No auto-merge.
• No direct host writes.
• No CI workflow edits.

Limitations

• Does not execute DAGs.
• Does not read Airflow runtime logs.
• Does not provide direct access to Airflow hosts.

Release readiness notes

Validated:

• Tool contract wiring and schema checks.
• Guardrails for allowlists, path controls, DAG markers, and blocked patterns.
• End-to-end PR workflow in sandbox (branch + commit + PR creation).

Out of scope:

• Multi-file edits.
• Delete/rename operations.
• Direct Airflow host mutations.
• Auto-merge or direct branch pushes bypassing PR review.

Recommended checks before publishing to npm / ClawHub:

1. Run npm run lint, npm run typecheck, and npm test.
2. Confirm openclaw.plugin.json metadata matches published package metadata.
3. Verify final package contents with npm pack --dry-run.

Rollback flow

1. Close the PR if not merged.
2. Delete the created branch.
3. If merged, revert the merge commit through standard GitHub process.

Development

npm install
npm run lint
npm run typecheck
npm test