YAML Workflow

YAML Workflow

CI/CD パイプライン、データ処理、DevOps 自動化のための軽量なワークフローエンジンです。再現可能でバージョン管理可能なワークフローを YAML で定義し、ローカル、CI、または Python がインストールされた任意のマシンで実行できます。

yaml-workflow を選ぶ理由

ほとんどのワークフローツールでは、サーバー、データベース、複雑なインフラストラクチャが必要です。yaml-workflow は GitOps のアプローチを採用し、ワークフローをコードと一緒にバージョン管理するプレーンな YAML ファイルとして扱います。

	yaml-workflow	Airflow / Prefect / Dagster
セットアップ	pip install yaml-workflow	サーバー、データベース、スケジューラー、ワーカー
設定	プレーンな YAML ファイル	Python DAG とインフラストラクチャの設定
依存関係	2 個（PyYAML、Jinja2）	50 個以上のパッケージ、Docker、PostgreSQL
ユースケース	ローカル自動化、スクリプト、CI/CD、データパイプライン	大規模なエンタープライズオーケストレーション
学習曲線	数分	数時間から数日
状態	ファイルベース、再開可能	データベースベース

次のような場合に yaml-workflow をお選びください。

• インフラストラクチャの負担なしで簡単なタスク自動化を行いたい
• バージョン管理された YAML で再現可能なパイプラインを定義したい
• 並列実行を伴うバッチ処理を行いたい
• 状態を永続化し、失敗後にワークフローを再開したい
• より優れたエラー処理を備えた、シェルスクリプトの軽量な代替手段が必要
• コードと一緒にリポジトリに保存する、GitOps に適したパイプラインを使いたい
• ローカルでも CI でも同じパイプラインを実行できる単一のツールが必要

機能

• Jinja2 テンプレートを使用した YAML 駆動のワークフロー定義
• 複数のタスクタイプ：shell、Python、file、template、HTTP、batch
• imports によるワークフローの構成 — ワークフロー間でステップを再利用
• エントリーポイントによるプラグインシステム — pip install yaml-workflow-myplugin
• ウォッチモード — ファイル変更時に再実行する --watch
• 実行せずにプレビューするドライランモード
• ワークフローの可視化（ASCII 分岐 DAG および Mermaid）
• 設定可能なワーカープールによる並列実行
• 状態の永続化と再開機能
• 設定可能な戦略による再試行メカニズム
• 名前空間付き変数（args、env、steps、batch）
• カスタムステップシーケンスと条件によるフロー制御
• @register_task デコレーターによる拡張可能なタスクシステム
• depends_on による並列ステップ実行 — 依存関係のないステップを同時に実行
• シークレットの検証 — 必須の環境変数が不足している場合、即座に失敗
• CI 統合とスクリプト向けの構造化出力（--format json）
• MCP サーバー — ワークフローを AI エージェントのツールとして公開（pip install yaml-workflow[mcp]）
• Web ダッシュボード — 実行状況の監視とワークフローの起動（pip install yaml-workflow[serve]）
• GitHub Action — uses: orieg/[email protected] で CI 内のワークフローを実行

ユースケース

• CI/CD パイプライン — YAML による複数ステップのビルド、テスト、デプロイのワークフロー
• データ処理 — 失敗時の再試行と再開に対応したバッチ ETL パイプライン
• DevOps 自動化 — シークレット管理と通知機能を備えたインフラストラクチャタスク
• AI/LLM パイプライン — 認証、再試行、バッチ処理を伴う API 呼び出しのオーケストレーション
• ローカル自動化 — シェルスクリプトを再現可能でパラメーター化されたワークフローに置き換え

クイックスタート

# Install (isolated CLI — recommended)
pipx install yaml-workflow            # Core CLI
pipx install 'yaml-workflow[all]'     # + web dashboard + MCP server

# Or with pip
pip install yaml-workflow

# Initialize example workflows
yaml-workflow init

# Run a workflow with parameters
yaml-workflow run workflows/hello_world.yaml name=Alice

ワークフローの例（hello_world.yaml）：

name: Hello World
description: A simple greeting workflow

params:
  name:
    type: string
    default: World

steps:
  - name: create_greeting
    task: template
    inputs:
      template: "Hello, {{ args.name }}!"
      output_file: greeting.txt

  - name: show_greeting
    task: shell
    inputs:
      command: cat greeting.txt

ワークフローを可視化する

yaml-workflow visualize workflows/data_pipeline.yaml

  Workflow: Data Pipeline

  ┌─────────────────┐
  │  detect_format  │
  │   python_code   │
  └─────────────────┘
           │
           ▼
  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐
  │  process_json  │  │  process_csv   │  │  process_xml   │  │ handle_unknown │
  │     shell      │  │     shell      │  │     shell      │  │     shell      │
  └────────────────┘  └────────────────┘  └────────────────┘  └────────────────┘
           │
           ▼
  ┌─────────────────┐
  │ generate_report │
  │   python_code   │
  └─────────────────┘

隣接する条件付きステップは、自動的に分岐としてグループ化されます。ドキュメントや GitHub でのレンダリング用にエクスポートするには、--format mermaid を使用してください。

ドライランモード

実行せずに、ワークフローで行われる処理をプレビューします。

yaml-workflow run workflows/hello_world.yaml name=Alice --dry-run

[DRY-RUN] Workflow: Hello World
[DRY-RUN] Steps: 2 to execute

  [DRY-RUN] Step 'create_greeting' — task: template — WOULD EXECUTE
    template: Hello, Alice!
    output_file: greeting.txt
  [DRY-RUN] Step 'show_greeting' — task: shell — WOULD EXECUTE
    command: cat greeting.txt

[DRY-RUN] Complete. 2 step(s) would execute, 0 would be skipped.
[DRY-RUN] No files were written. No tasks were executed.

ワークフローの構成

imports を使って、複数のワークフローでステップを再利用します。

# main.yaml
imports:
  - ./shared/logging_steps.yaml
  - ./shared/common_params.yaml

steps:
  - name: my_step
    task: shell
    inputs:
      command: echo "runs after imported steps"

インポートしたステップは先頭に追加されます。インポートしたパラメーターはデフォルト値となり、メインのワークフローで上書きできます。循環参照を検出しながら、推移的なインポートにも対応しています。

並列ステップ

depends_on を使って、依存関係のないステップを並行して実行します。

steps:
  - name: fetch_api
    task: http.request
    inputs: {url: "https://api.example.com/data"}

  - name: fetch_db
    task: python_code
    inputs:
      code: "result = query_database()"

  - name: merge
    task: python_code
    depends_on: [fetch_api, fetch_db]
    inputs:
      code: |
        api_data = steps["fetch_api"]["result"]
        db_data = steps["fetch_db"]["result"]
        result = {"merged": True}

ウォッチモード

開発中にファイルの変更を検知し、自動的に再実行します。

yaml-workflow run workflows/hello_world.yaml name=Alice --watch

ワークフローファイルと、インポートされたすべてのファイルを監視します。停止するには Ctrl+C を押します。

GitHub Actions

yaml-workflow action を使って、CI でワークフローを実行します。

- name: Run pipeline
  uses: orieg/[email protected]
  id: pipeline
  with:
    workflow: workflows/deploy.yaml
    params: |
      env=production
      version=1.2.0
    format: json

- name: Use results
  run: echo '${{ steps.pipeline.outputs.result }}'

Docker と Kubernetes

Python をインストールせずに、どこでも実行できます。

# Run a workflow in Docker
docker run --rm -v $(pwd)/workflows:/app/workflows \
  ghcr.io/orieg/yaml-workflow run /app/workflows/pipeline.yaml

# Start the web dashboard
docker run -p 8080:8080 -v $(pwd)/workflows:/app/workflows \
  ghcr.io/orieg/yaml-workflow

Helm チャートを使って Kubernetes にデプロイします。

helm install my-workflows ./helm/yaml-workflow \
  --set-file workflows.files.pipeline\\.yaml=workflows/pipeline.yaml

ArgoCD（GitOps）および Argo Workflows と互換性があります。Kubernetes ガイドをご覧ください。

その他のコマンド

# List available workflows
yaml-workflow list

# Validate a workflow (with JSON output for CI)
yaml-workflow validate workflows/hello_world.yaml --format json

# Resume a failed workflow
yaml-workflow run workflows/hello_world.yaml --resume

# Structured output for scripting
yaml-workflow run workflows/pipeline.yaml --format json --output results.json

ドキュメント

詳細なドキュメントは orieg.github.io/yaml-workflow でご覧いただけます。

• はじめに - インストールと最初のワークフロー
• タスクの種類 - シェル、Python、ファイル、テンプレート、バッチの各タスク
• ワークフローの構造 - YAML 設定リファレンス
• テンプレート化 - Jinja2 による変数置換
• 状態管理 - 永続化と再開
• タスク開発 - カスタムタスクの作成
• API リファレンス - API ドキュメント全般

貢献

コントリビューションを歓迎します。開発環境のセットアップとガイドラインについては、コントリビューションガイドをご覧ください。

ライセンス

このプロジェクトは MIT ライセンスで公開されています。詳細は LICENSE ファイルをご覧ください。