GitHub Actions ワークフローを構成する

10 分

ここでは、ワークフローファイル内の一般的な構成について説明します。また、イベントの種類のカテゴリ、ワークフローの無効化と削除、セキュリティのベストプラクティスのためのアクションの特定のバージョンの使用についても説明します。

スケジュール化されたイベントに対して実行するワークフローを構成する

前述のように、GitHub で特定のアクティビティが発生したとき、GitHub の外部のイベントが発生したとき、またはスケジュールされた時刻に実行するように、ワークフローを構成できます。 POSIX cron 構文を使用して、scheduleイベントにより、特定の UTC 時刻に実行するワークフローをトリガーできます。この cron 構文には 5 つの * フィールドがあり、各フィールドは単位時間を表します。

ワークフローファイルでイベントをスケジュールするための 5 つの単位時間フィールドの画像。

たとえば、ワークフローを 15 分ごとに実行する場合、 schedule イベントは次の例のようになります。

on:
  schedule:
    - cron:  '*/15 * * * *'

さらに毎週日曜日の午前 3 時にワークフローを実行する場合、schedule イベントは次のようになります。

on:
  schedule:
    - cron:  '0 3 * * SUN'

また、演算子を使用して値の範囲を指定したり、スケジュールされたワークフローをダイヤルインしたりすることもできます。スケジュールされたワークフローを実行できる最短間隔は、5 分ごとに 1 回で、それらは既定またはベースブランチで最新のコミットで実行されます。

手動のイベントに対して実行するようにワークフローを構成する

スケジュールされたイベントに加えて、workflow_dispatch イベントを使用して手動でワークフローをトリガーすることもできます。このイベントにより、GitHub REST API を使用するか、GitHub のリポジトリ内で [アクション] タブの [ワークフローの実行] ボタンを選択して、ワークフローを実行できます。 workflow_dispatchを使用すると、ワークフローを実行するブランチを選択し、GitHub が UI のフォーム要素として表示するオプションのinputsを設定できます。

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'

workflow_dispatch に加えて、GitHub API を使用して、repository_dispatch という Webhook イベントをトリガーすることもできます。このイベントを使用すると、GitHub の外部で発生するアクティビティのワークフローをトリガーできます。これは基本的に、アクションまたは webhook からワークフローをトリガーするように GitHub に要求するリポジトリへの HTTP 要求として機能します。この手動のイベントを使用するには、2 つの操作を行う必要があります。要求本文で Webhook イベント名を使用して、GitHub エンドポイント /repos/{owner}/{repo}/dispatches に POST 要求を送信し、repository_dispatch イベントを使用するようにワークフローを構成します。

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/dispatches \
  -d '{"event_type":"event_type"}'

on:
  repository_dispatch:
    types: [opened, deleted]

Webhook イベントに対して実行するワークフローを構成する

最後に、特定の Webhook イベントが GitHub で発生したときに実行するようにワークフローを構成できます。ほとんどの Webhook イベントは、1 つの Webhook に対して複数のアクティビティからトリガーできます。 Webhook に複数のアクティビティが存在する場合は、ワークフローをトリガーするアクティビティの種類を指定できます。たとえば、 check_run イベントのワークフローを実行できますが、 rerequested または requested_action アクティビティの種類に対してのみ実行できます。

on:
  check_run:
    types: [rerequested, requested_action]

Repository_dispatch

repository_dispatch は GitHub Actions のカスタムイベントであり、外部システム (または他の GitHub ワークフロー) が GITHub API に POST 要求を送信してワークフローを手動でトリガーできるようにします。これにより、リポジトリでワークフローを開始する必要がある外部のツール、スクリプト、またはシステムとの柔軟な自動化と統合が可能になります。

活用事例

外部 CI/CD ツールからワークフローをトリガーします。
複数リポジトリのデプロイを調整します (たとえば、Repo A はビルドを完了→リポジトリ B をトリガーします)。
外部イベント (Webhook、監視アラート、GitHub 外の CRON ジョブ) に基づいて自動化を開始します。
リポジトリ間または monorepos 内でワークフロー実行を連結する。

repository_dispatchをリッスンするワークフローの例

name: Custom Dispatch Listener

on:
  repository_dispatch:
    types: [run-tests, deploy-to-prod]  # Optional filtering

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Echo the payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload value: ${{ github.event.client_payload.env }}"

主な要素:

種類:オプション。 run-tests、deploy-to-prodなどのカスタムイベントの種類を定義します。
github.event.client_payload: ディスパッチイベントで渡された他のカスタムデータへのアクセス。
github.event.action: 送信されたevent_typeの名前。

API を使用したイベントのトリガー

GITHub REST API v3 エンドポイントに POST 要求を送信する必要があります。

POST https://api.github.com/repos/OWNER/REPO/dispatches

認証

リポジトリスコープを持つ個人用アクセストークン (PAT) が必要です。
組織の場合は、トークンの適切なアクセス設定を確認します。

コマンド構造のサンプル

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"run-tests","client_payload":{"env":"staging"}}'

ペイロードの構造

{
  "event_type": "run-tests",
  "client_payload": {
    "env": "staging"
  }
}

パラメーター

フィールド	タイプ	説明	必須
`event_type`	文字列	イベントのカスタム名。この名前は、ワークフロートリガーの types 値にマップされます	イエス
`client_payload`	オブジェクト	カスタムデータをワークフローに送信する任意の JSON ペイロード (github.event.client_payload)	いいえ

Repository_dispatch パラメーターの内訳

GitHub API エンドポイントに POST 要求を行うときは、2 つの主要なパラメーターを含む JSON 本文を渡す必要があります。

イベントタイプ
client_payload

イベントタイプ

定義する必要なカスタム文字列。 GitHub は、この値をディスパッチの "アクション" または "型" として扱います。これは、ワークフローをトリガーした原因を特定し、特定の種類をリッスンしているワークフローをフィルター処理するために使用されます。

形式：
- 型: string
- 例: "deploy"、"run-tests"、"sync-db"、"build-docker"
ワークフローでの使用: 特定のイベントの種類をリッスンし、ワークフロー内の値にアクセスするために使用されます。これは、複数の目的で 1 つのワークフローを再利用するのに役立ち、自動化をより整理し、イベントドリブンにします。
例：

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"

client_payload

ディスパッチと共にカスタムデータを送信できる自由形式の JSON オブジェクト。構造を定義すると、ワークフロー内でアクセスできます。

形式：
- 型: オブジェクト
- カスタムキーと値
ワークフローでの使用: このオブジェクトは、複数環境のデプロイ、バージョン管理されたリリース、または別のシステムまたはパイプラインからのコンテキストの受け渡しに使用され、入力引数と同様に、パラメーター化されたワークフローを有効にします。
例：

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"

ペイロードの内訳の例

{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

条件付きキーワードを使用する

ワークフローファイル内で、コンテキスト情報にアクセスし、式を評価できます。式は、ステップを実行する必要があるかどうかを判断するために、ワークフローファイル内で条件 if キーワードと共によく使用されますが、サポートされている任意のコンテキストと式を使用して、条件を作成できます。ワークフローで条件を使用する場合は、特定の構文 ${{ <expression> }}を使用する必要があることを理解することが重要です。この構文は、式を文字列として扱うのではなく、式を評価するように GitHub に指示します。

たとえば、 if 条件を使用して、 github.ref (ワークフロー実行をトリガーした分岐またはタグ参照) が refs/heads/mainと一致するかどうかを確認するワークフローなどです。続行するには、ワークフローは次のようになります。

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      ...

この例では、構文に ${{ }} がないことに注意してください。条件 if のような一部の式では、式の構文を省略できます。 GitHub では、これらの一般的ないくつかの式が自動的に評価されますが、どの式が GitHub で自動的に評価されるか忘れた場合に備えて、常にそれらを含めるようにすることができます。

ワークフローの構文と式の詳細については、GitHub Actions のワークフロー構文に関するページを参照してください。

ワークフローの無効化と削除

ワークフローをリポジトリに追加した後に、ワークフローを一時的に無効にする必要がある状況に気付くことがあります。 GitHub で、または GitHub REST API を使用して、リポジトリからファイルを削除することなく、ワークフローがトリガーされないようにすることができます。ワークフローを再び有効にする場合は、同じメソッドを使用して簡単にそれを実行できます。

GitHub でのワークフローの無効化のスクリーンショット。

ワークフローを無効にすると、次のような状況で役立つ場合があります。

ワークフローのエラーによって、過度に多くの要求や誤った要求が生成され、外部のサービスに悪影響を与えている。
重要でない、アカウントに対して過度に多くの時間を費やしているワークフローを一時的に停止する必要がある。
停止しているサービスに対して要求を送信しているワークフローを一時停止する必要がある。
フォークを操作しており、それに含まれる一部のワークフロー (スケジュールされたワークフローなど) のすべての機能が必要であるとは限らない。

また、GitHub UI の [アクション] タブから、または GitHub API エンドポイント DELETE /repos/{owner}/{repo}/actions/runs/{run_id} を使用して、進行中のワークフロー実行を取り消すこともできます。ワークフローの実行を取り消すと、GitHub はその実行内のすべてのジョブとステップを取り消します。

組織のテンプレート化されたワークフローを使用する

組織内で複数のチームが使用するワークフローがある場合は、リポジトリごとに同じワークフローを再作成する必要はありません。代わりに、組織の .github リポジトリで定義されているワークフローテンプレートを使用して、組織全体の整合性を促進できます。組織内のすべてのメンバーは、組織テンプレートワークフローを使用できます。また、その組織内のすべてのリポジトリには、これらのテンプレートワークフローへのアクセス権があります。

これらのワークフローを見つけるには、組織内のリポジトリの [アクション] タブに移動し、[新しいワークフロー] を選択して、"組織名によって作成されたワークフロー" というタイトルの組織のワークフローテンプレートセクションを見つけます。たとえば、モナという組織には、次に示すようなテンプレートワークフローがあります。

Mona による、greet and triage というテンプレート組織ワークフローのスクリーンショット。

特定のバージョンのアクションを使用する

ワークフロー内のアクションを参照する場合は、アクション自体ではなく、そのアクションの特定のバージョンを参照することが推奨されます。特定のバージョンを参照することにより、ワークフローを中断する可能性のある予期しない変更がアクションにプッシュされることから保護します。特定のバージョンのアクションを参照できる方法をいくつか示します。

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

参照によっては安全なものとそうでないものがあります。たとえば、特定のブランチを参照すると、そのブランチからの最新の変更からアクションが実行されます。これは、必要な場合もあれば望まない場合もあります。特定のバージョン番号またはコミットの SHA ハッシュを参照することで、実行しているアクションのバージョンについてさらに詳細に指定できます。安定性とセキュリティの向上のため、ワークフロー内でリリースされたアクションのコミット SHA を使用することが推奨されます。

フィードバック

このページはお役に立ちましたか?