信頼性の高いワークフローを構築する - 出力、コンテキスト、トリガー、およびジョブ間のハンドオフ

このユニットでは、次の内容について説明します。

• ステップとジョブの出力結果を使用して、ワークフローを通じてデータをやり取りする方法

• 構成と制御にGitHub コンテキストを使用する方法

• 安全なトリガーと防御のゲーティングを使用してワークフローを設計する方法

• ワークフローが正しいコンテキストでのみ実行されるようにする方法

• 構造化データとイベント ロジックを使用して信頼性の高いワークフローを構築する方法

自律性は、想定に頼らず、設計されなければなりません。

タスクによって異なるリスクが伴います。 適切なエージェント アーキテクチャでは、ポリシーを使用して、どこでも同じルールを適用するのではなく、さまざまな自律レベルを表します。

単純なリスクベースの自律性モデルは、次のようになります。

実装: リスクの高い実行のための環境承認

環境は、デプロイや保護されたシークレットへのアクセスなど、危険なアクションの強力な制御ポイントを提供します。 必要なレビュー担当者で環境が構成されている場合、その環境を対象とするジョブは、承認が付与されるまで一時停止します。

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
    steps:
      - run: echo "Deploying to production..."

この設計により、エージェントは運用環境に影響を与えるアクションを個別に実行できないようにしながら、変更を準備できます。

出力はワークフロー コントラクト (ステップ出力とジョブ出力と env) です

ダウンストリームのステップまたはジョブが使用する必要がある情報をワークフローが生成する場合は、そのデータを "ログのみ" ではなく明示的な出力として扱います。

次の原則を教え,応用します。

• ステップ出力は、同じジョブ内のステップ間で値を渡します。

• ジョブ出力は、ジョブ間で (ジョブの依存関係を介して) 値を渡します。

• 環境変数はランタイム動作を構成しますが、構造化データ フローの出力を置き換えるべきではありません。

例示パターン (表示されるメカニズムは示されていますが、試験の形ではありません):

- id: generate_plan
  run: |
    echo "plan=high level steps..." >> "$GITHUB_OUTPUT"

- run: |
    echo "Plan: ${{ steps.generate_plan.outputs.plan }}"

ジョブ間共有の場合は、ジョブ出力を発行し、依存ジョブから参照します。

jobs:
  plan:
    outputs:
      plan: ${{ steps.generate_plan.outputs.plan }}
    steps:
      - id: generate_plan
        run: echo "plan=..." >> "$GITHUB_OUTPUT"

  implement:
    needs: plan
    steps:
      - run: echo "Using plan: ${{ needs.plan.outputs.plan }}"

コンテキスト: GitHub対 vars 対 env

適切な目的に適切なコンテキストを使用します。

• github.* →イベント メタデータとランタイムの決定 ("この実行のトリガーは何ですか?")

• vars.* →再利用するように設計された一元的に管理された構成値

• env.* →ジョブ レベルの環境変数とランタイム構成

安全なトリガーと防御的なゲート・コントロール

ワークフローが PR 用に設計されている場合でも、リポジトリには多くの場合、複数のトリガーがあります。 "PR 専用" の動作が誤って PR コンテキストなしで実行されないように、防御的なゲーティングを追加します。

教える一般的なパターン:

• ジョブ レベルの条件を使用して、PR に依存するアクションが PR イベントに関連付けられている場合にのみ実行されるようにします。

プルリクエストのみの動作に対する守りのゲーティング

ワークフローがプル要求に対してのみ実行されるように意図されている場合でも、他のイベント (プッシュ、workflow_dispatch、スケジュールなど) によってトリガーされる可能性があります。 追加のセーフガードがないと、プル要求に対するコメントや変更の評価など、PR 固有の手順が失敗したり、予期せず動作したりする可能性があります。

これを防ぐには、プル要求に関連付けられているときにのみワークフローが実行されるように するジョブ レベルの条件 を追加します。

name: PR Validation

on:
  pull_request:
    branches: [ main ]
  workflow_dispatch: # allows manual runs, but still gated below

jobs:
  validate-pr:
    # Defensive gating: only run if this is actually a PR context
    if: github.event_name == 'pull_request'

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run tests
        run: npm test

      - name: Comment on PR
        run: echo "Validation complete"

重要なポイント: 計画と信号を構造化された出力として扱い、イベント対応ロジックによって保護すると、ワークフローの信頼性が向上します。

次に、実行を監査可能にし、ツールとシークレットを制御し、フックベースのガードレールと信頼性パターンを構築することで、エージェントを安全に運用します。