eve-pipelines-workflows

Eve パイプラインとワークフロー

これらのパターンを使って、ビルドやデプロイのアクションを自動化し、ワークフロージョブを呼び出します。

パイプライン（v2 ステップ）

• .eve/manifest.yaml の pipelines の下にパイプラインを定義します。
• ステップには action、script、agent を指定できます。
• depends_on を使って実行順序を制御します。
• 組み込みアクションには、build、release、deploy、run、job、create-pr があります。
• 手動で実行します：
  • eve pipeline list
  • eve pipeline show <project> <name>
  • eve pipeline run <name> --ref <sha> --env <env> --repo-dir ./my-app
• マニフェストにはトリガーブロックがあり、GitHub や Slack のウェブフックからパイプラインの実行を作成できます。

組み込みアクション

build アクション

ビルドアクションは、追跡および監視可能な BuildSpec レコードと BuildRun レコードを作成します。

• データベースに BuildSpec（ビルド対象の定義）と BuildRun（実行記録）を作成します。
• 出力には build_id と image_digests マップ（サービス名から SHA256 ダイジェストへの対応）が含まれます。
• これらの出力は依存するステップに自動的に渡されます（release は build_id を使用します）。
• ビルドを個別に確認できます：eve build show、eve build diagnose、eve build runs、eve build logs

エージェントステップ

パイプラインのステージで AI エージェントジョブを実行する場合は、agent ステップを使います。

pipelines:
  remediation:
    steps:
      - name: analyze
        agent:
          prompt: "Analyze the failure and propose a fix"

標準的なパイプラインの流れ

すべてのデプロイパイプラインでは、次のパターンに従ってください。

pipelines:
  deploy:
    steps:
      - name: build
        action:
          type: build
          # Creates BuildSpec + BuildRun, outputs build_id + image_digests
      - name: release
        depends_on: [build]
        action:
          type: release
          # References build_id, derives digests from BuildArtifacts
      - name: deploy
        depends_on: [release]
        action:
          type: deploy
          env_name: staging
          # Uses digest-based image refs for immutable deploys

昇格ワークフロー

test で一度だけビルドし、同じビルド成果物を staging／production に昇格させます。

• ビルドステップでは、成果物（イメージダイジェスト）を含む BuildRun が作成されます。
• リリースでは build_id が引き継がれ、環境間で同一のイメージが使われます。
• このパターンにより、テストしたものとまったく同じものをデプロイできます。

パイプラインの実行を追跡します。

eve job list --phase active
eve job follow <job-id>
eve job result <job-id>

パイプラインのログとストリーミング

パイプラインの実行をリアルタイムで監視します。

# Snapshot logs for a run
eve pipeline logs <pipeline> <run-id>

# Real-time SSE streaming
eve pipeline logs <pipeline> <run-id> --follow

# Stream specific step
eve pipeline logs <pipeline> <run-id> --follow --step <name>

失敗したステップには、失敗のヒントと、該当する場合はビルド診断へのリンクが表示されます。

パイプラインエイリアスとしての環境デプロイ

マニフェストで環境に pipeline が設定されている場合、eve env deploy <env> --ref <sha> は直接デプロイする代わりに、そのパイプラインを自動的に実行します。

基本的な使い方

# Triggers the configured pipeline for test environment
eve env deploy test --ref 0123456789abcdef0123456789abcdef01234567

# Pass inputs to the pipeline
eve env deploy staging --ref 0123456789abcdef0123456789abcdef01234567 --inputs '{"release_id":"rel_xxx"}'

# Bypass pipeline and do direct deploy
eve env deploy staging --ref 0123456789abcdef0123456789abcdef01234567 --direct

昇格フローの例

# 1. Build and deploy to test environment
eve env deploy test --ref 0123456789abcdef0123456789abcdef01234567

# 2. Get release info from the test build
eve release resolve v1.2.3
# Output: rel_xxx

# 3. Promote to staging using the release_id
eve env deploy staging --ref 0123456789abcdef0123456789abcdef01234567 --inputs '{"release_id":"rel_xxx"}'

主な動作

• environments.<env>.pipeline が設定されている場合、eve env deploy <env> はそのパイプラインを実行します。
• パイプラインを経由せずに直接デプロイするには、--direct フラグを使います。
• パイプラインの実行に入力を渡すには、--inputs '{"key":"value"}' を使います。
• デフォルトの入力は、マニフェストの environments.<env>.pipeline_inputs で設定できます。
• --ref フラグは、デプロイする git SHA（40 文字の SHA、または --repo-dir 経由で解決される ref）を指定します。
• 環境変数とシークレットは通常どおり補間されます。

このパターンを使うと、下位環境で一度ビルドし、同じ成果物を上位環境へ昇格させるワークフローを実現できます。

ワークフロー

• マニフェストの workflows の下にワークフローを定義します。
• db_access が設定されている場合は、その値（read_only、read_write）が適用されます。
• 呼び出し時の resource_refs は、依存するステップを含むすべてのワークフローステップでデフォルトで利用できます。ワークフロー全体のデフォルトポリシーを設定するにはワークフローレベルの resource_refs を使い、ステップレベルの resource_refs で上書きします。
  • inherit／all：呼び出し時のすべての ref を渡します。
  • none：ref を渡しません。
  • [brief, design-system]：name、label、mount_path、uri、metadata.name が一致する ref のみを渡します。
• 手動で呼び出します：
  • eve workflow list
  • eve workflow show <project> <name>
  • eve workflow run <project> <name> --input '{"k":"v"}'（結果を待たずに実行）
  • eve workflow invoke <project> <name> --input '{"k":"v"}'（結果を待機）
  • eve workflow logs <job-id>
• 呼び出すとジョブが作成されます。通常のジョブコマンドで追跡できます。

ワークフローのヒント

hints を使って、ゲーティング、タイムアウト、ハーネスの設定を制御します。

workflows:
  remediate:
    hints:
      gates: ["remediate:proj_abc123:staging"]

条件付きステップ

上流ステップの結果に応じて、後続のステップをスキップします。条件では名前付きの上流ステップを参照し、ディスパッチ時に評価されます。

workflows:
  triage-and-act:
    steps:
      - name: triage
        agent: { prompt: "Classify this incident" }
      - name: deep
        depends_on: [triage]
        condition: "triage.status == 'complex'"   # skip if false
        agent: { prompt: "Run deep analysis" }

条件では、上流ステップのステータスに対して == と != を使用できます。参照するステップは depends_on に含まれている必要があります。マニフェストの同期時に、参照先のないステップや不正な条件構文は検証で拒否されます。

ステップ単位のハーネスのオーバーライド

ステップごとにハーネスを固定またはオーバーライドできます（ワークフローのステップとパイプラインのステップで、同じ形式を使用します）。

steps:
  - name: classify
    harness: claude
    harness_profile: claude-sonnet
    harness_options:
      model: claude-sonnet-4-7
      reasoning_effort: medium
      temperature: 0.2
    agent: { prompt: "Classify this" }

ステップ単位の値は、エージェントが解決したデフォルト値より優先されます。harness_profile には、呼び出し元が選択できるように ${inputs.model} のようなテンプレートを指定できます。

ワークフローの env_overrides

ワークフロー、ステップ、呼び出しの3つのレイヤーで環境変数を設定できます。ランタイムはこの順序で統合し、後のレイヤーが優先されます。${secret.KEY} でシークレットを参照できます。リゾルバーはログ内のシークレットをマスキングします。

workflows:
  remediate:
    env_overrides:
      LOG_LEVEL: info
    steps:
      - name: act
        env_overrides:
          LOG_LEVEL: debug          # step wins over workflow
          API_KEY: ${secret.VENDOR_TOKEN}
        agent: { prompt: "Remediate" }

呼び出し元は、呼び出し時に3つ目のレイヤーを追加できます。

eve workflow invoke <project> remediate --input '{"k":"v"}' --env-override DRY_RUN=true

パイプラインの env は実行の env_name に引き継がれるため、ステップごとに再宣言しなくても適切なスコープが適用されます。

ジョブ単位のハーネスのオーバーライド（アドホックジョブ）

ワークフロー外でアドホックジョブを実行する場合は、作成時の呼び出しでハーネスをオーバーライドします。

eve job create --description "Investigate" \
  --harness claude \
  --profile claude-sonnet

# Or pass a full override object:
eve job create --description "..." --harness-override-file ./override.json
# override.json: { "harness": "...", "model": "...", "reasoning_effort": "...", "variant": "...", "temperature": 0.2 }

このオーバーライドはディスパッチとクレームを通じてエンドツーエンドで引き継がれ、エージェントが解決した値より優先されます。

Slack 通知、再試行、ファイル参照

• ワークフローの hints.slack は、ステップの開始・完了・失敗を設定済みのチャンネルに投稿します。
• 前回の呼び出しで失敗したステップと、上流ステップの失敗によって失敗したステップを再試行できます。
  • eve workflow retry <root-job-id> --failed
  • eve workflow retry <root-job-id> --from <step>
• ワークフローのステップではファイル参照（パスを指す resource_refs エントリー）を使用できます。これらは他の参照とともにステップのワークスペースに展開されます。