ワークフローをトリガーするイベント

ワークフローをトリガーするイベントについて

ワークフロー トリガーは、ワークフローの実行を引き起こすイベントです。 ワークフロー トリガーの使い方について詳しくは、「ワークフローのトリガー」をご覧ください。

イベントによっては、複数のアクティビティの種類があります。 このようなイベントでは、ワークフローの実行をトリガーするアクティビティの種類を指定できます。 各アクティビティの種類の意味について詳しくは、「Webhook のイベントとペイロード」をご覧ください。

branch_protection_rule

ワークフロー リポジトリ内のブランチ保護ルールが変更されたときにワークフローを実行します。 ブランチ保護ルールについて詳しくは、「保護されたブランチについて」をご覧ください。 ブランチ保護ルール API については、GraphQL API ドキュメントの「オブジェクト」または「ブランチとその設定用 REST API エンドポイント」をご覧ください。

たとえば、ブランチ保護ルールが created または deleted だったときにワークフローを実行できます。

on:
  branch_protection_rule:
    types: [created, deleted]

check_run

チェック実行に関連するアクティビティが発生したときにワークフローを実行します。 チェックの実行は、個別のテストであり、チェックスイートの一機能です。 詳しくは、「REST API を使用してチェックを操作する」をご覧ください。 チェック実行 API については、GraphQL API ドキュメントの「オブジェクト」または「チェック実行用 REST API エンドポイント」をご覧ください。

たとえば、チェック実行が rerequested または completed だったときにワークフローを実行できます。

on:
  check_run:
    types: [rerequested, completed]

check_suite

チェック スイートのアクティビティが発生したときにワークフローを実行します。 チェック スイートは、特定のコミットに対して作成されたチェック実行のコレクションです。 チェック スイートでは、スイート内のチェック実行の状態と結果をまとめます。 詳しくは、「REST API を使用してチェックを操作する」をご覧ください。 チェック スイート API については、GraphQL API ドキュメントの「オブジェクト」または「チェック スイート用 REST API エンドポイント」をご覧ください。

たとえば、チェック スイートが completed だったときにワークフローを実行できます。

on:
  check_suite:
    types: [completed]

create

誰かがワークフローのリポジトリに Git 参照 (Git ブランチまたはタグ) を作成したときにワークフローを実行します。 Git 参照を作成するための API については、GraphQL API ドキュメントの「ミューテーション」または「Git リファレンス用 REST API エンドポイント」をご覧ください。

たとえば、create イベントが発生したときにワークフローを実行できます。

on:
  create

delete

誰かがワークフローのリポジトリで Git 参照 (Git ブランチまたはタグ) を削除したときにワークフローを実行します。 Git 参照を削除するための API については、GraphQL API ドキュメントの「ミューテーション」または「Git リファレンス用 REST API エンドポイント」をご覧ください。

たとえば、delete イベントが発生したときにワークフローを実行できます。

on:
  delete

deployment

誰かがワークフローのリポジトリにデプロイを作成したときにワークフローを実行します。 コミット SHA で作成されたデプロイメントには、Git 参照がないことがあります。デプロイメントを作成するための API については、GraphQL API ドキュメントの「ミューテーション」または 「リポジトリの REST API エンドポイント」をご覧ください。

たとえば、deployment イベントが発生したときにワークフローを実行できます。

on:
  deployment

deployment_status

サード パーティによってデプロイの状態が提供されたときにワークフローを実行します。 コミット SHA で作成されたデプロイは Git 参照がない場合があります。デプロイ状態を作成するための API の詳細については、GraphQL API ドキュメントの「ミューテーション」または 「デプロイ用の REST API エンドポイント」を参照してください。

たとえば、deployment_status イベントが発生したときにワークフローを実行できます。

on:
  deployment_status

discussion

ワークフローのリポジトリ内のディスカッションが作成または変更されたときにワークフローを実行します。 ディスカッションのコメントに関連するアクティビティには、discussion_comment イベントを使います。 ディスカッションについて詳しくは、「ディスカッションについて」をご覧ください。 GraphQL API については、「オブジェクト」をご覧ください。

たとえば、ディスカッションが created、edited、または answered だったときにワークフローを実行できます。

on:
  discussion:
    types: [created, edited, answered]

discussion_comment

ワークフローのリポジトリ内のディスカッションのコメントが作成または変更されたときにワークフローを実行します。 ディスカッションのコメントではなくディスカッションに関連するアクティビティには、discussion イベントを使います。 ディスカッションについて詳しくは、「ディスカッションについて」をご覧ください。 GraphQL API については、「オブジェクト」をご覧ください。

たとえば、ディスカッション コメントが created または deleted だったときにワークフローを実行できます。

on:
  discussion_comment:
    types: [created, deleted]

fork

誰かがリポジトリをフォークしたときにワークフローを実行します。 REST API については、「フォーク用の REST API エンドポイント」をご覧ください。

たとえば、fork イベントが発生したときにワークフローを実行できます。

on:
  fork

gollum

誰かが Wiki ページを作成または更新したときにワークフローを実行します。 詳しくは、「ウィキについて」を参照してください。

たとえば、gollum イベントが発生したときにワークフローを実行できます。

on:
  gollum

issue_comment

issue または pull request のコメントが作成、編集、または削除されたときにワークフローを実行します。 issue コメント API については、GraphQL API ドキュメントの「オブジェクト」または REST API ドキュメントの「Webhook のイベントとペイロード」をご覧ください。

たとえば、issue または pull request のコメントが created または deleted だったときにワークフローを実行できます。

on:
  issue_comment:
    types: [created, deleted]

issue のみまたは pull request のみの issue_comment

issue_comment イベントは、issue と pull request の両方に関するコメントで発生します。 条件で github.event.issue.pull_request プロパティを使うと、トリガーするオブジェクトが issue か pull request かによって異なるアクションを実行できます。

たとえば、このワークフローでは、issue_comment イベントが pull request から発生した場合にのみ pr_commented ジョブを実行します。 issue_comment イベントが issue から発生した場合にのみ issue_commented ジョブが実行されます。

on: issue_comment

jobs:
  pr_commented:
    # This job only runs for pull request comments
    name: PR comment
    if: ${{ github.event.issue.pull_request }}
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo A comment on PR $NUMBER
        env:
          NUMBER: ${{ github.event.issue.number }}

  issue_commented:
    # This job only runs for issue comments
    name: Issue comment
    if: ${{ !github.event.issue.pull_request }}
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo A comment on issue $NUMBER
        env:
          NUMBER: ${{ github.event.issue.number }}

issues

ワークフローのリポジトリ内の issue が作成または変更されたときにワークフローを実行します。 issue のコメントに関連するアクティビティには、issue_comment イベントを使います。 issue について詳しくは、「Issueについて」をご覧ください。 問題の API の詳細については、GraphQL API ドキュメントの「オブジェクト」または「issue 用の REST API エンドポイント」を参照してください。

たとえば、issue が opened、edited、または milestoned だったときにワークフローを実行できます。

on:
  issues:
    types: [opened, edited, milestoned]

label

ワークフローのリポジトリ内のラベルが作成または変更されたときにワークフローを実行します。 ラベルについて詳しくは、「ラベルを管理する」をご覧ください。 ラベル API の詳細については、GraphQL API ドキュメントの「オブジェクト」または「ラベル用の REST API エンドポイント」を参照してください。

issue、pull request、またはディスカッションに対してラベルが追加または削除されたときにワークフローを実行する場合は、代わりに issues、pull_request、pull_request_target、または discussion イベントにはアクティビティの種類 labeled または unlabeled を使います。

たとえば、ラベルが created または deleted だったときにワークフローを実行できます。

on:
  label:
    types: [created, deleted]

merge_group

マージ キューに pull request が追加されたときにワークフローを実行し、マージ グループにその pull request を追加します。 詳しくは、「pull request とマージ キューのマージ」をご覧ください。

たとえば、checks_requested イベントが発生したときにワークフローを実行できます。

on:
  pull_request:
    branches: [ "main" ]
  merge_group:
    types: [checks_requested]

milestone

ワークフローのリポジトリ内のマイルストーンが作成または変更されたときにワークフローを実行します。 マイルストーンについて詳しくは、「マイルストーンについて」をご覧ください。 マイルストーン API の詳細については、GraphQL API ドキュメントの「オブジェクト」または「マイルストーン用の REST API エンドポイント」を参照してください。

マイルストーンに対して issue が追加または削除されたときにワークフローを実行する場合は、代わりに issues イベントにはアクティビティの種類 milestoned または demilestoned を使います。

たとえば、マイルストーンが opened または deleted だったときにワークフローを実行できます。

on:
  milestone:
    types: [opened, deleted]

page_build

リポジトリに対して GitHub Pages が有効になっている場合、GitHub Pages の公開元であるブランチに誰かがプッシュしたときにワークフローを実行します。 GitHub Pages の発行元について詳しくは、「GitHub Pages サイトの公開元を設定する」をご覧ください。 REST API については、「リポジトリの REST API エンドポイント」をご覧ください。

たとえば、page_build イベントが発生したときにワークフローを実行できます。

on:
  page_build

public

ワークフローのリポジトリがプライベートからパブリックに変更されたときにワークフローを実行します。 REST API については、「リポジトリの REST API エンドポイント」をご覧ください。

たとえば、public イベントが発生したときにワークフローを実行できます。

on:
  public

pull_request

ワークフローのリポジトリ内の pull request のアクティビティが発生したときにワークフローを実行します。 たとえば、アクティビティの種類が指定されていない場合、pull request を開いたり、再度開いたりしたとき、または pull request の head ブランチが更新されたときにワークフローが実行されます。 pull request レビュー、pull request レビュー コメント、または pull request コメントに関連するアクティビティには、代わりに pull_request_review、pull_request_review_comment、または issue_comment イベントを使います。 pull request API については、GraphQL API ドキュメントの「オブジェクト」または「Pull request 用 REST API エンドポイント」をご覧ください。

このイベントの GITHUB_SHA が pull request マージ ブランチの最後のマージ コミットであることに注意してください。 pull request の head ブランチへの最後のコミットのコミット ID を取得する場合は、代わりに github.event.pull_request.head.sha を使います。

たとえば、pull request を開いたり再度開いたりしたときにワークフローを実行できます。

on:
  pull_request:
    types: [opened, reopened]

イベント コンテキストを使って、ワークフロー内のジョブを実行するタイミングをさらに制御できます。 たとえば、このワークフローは pull request でレビューが要求されたときに実行されますが、specific_review_requested ジョブは octo-team によるレビューの要求時にのみ実行されます。

on:
  pull_request:
    types: [review_requested]
jobs:
  specific_review_requested:
    runs-on: ubuntu-latest
    if: ${{ github.event.requested_team.name == 'octo-team'}}
    steps:
      - run: echo 'A review from octo-team was requested'

pull request の head またはベース ブランチに基づいて pull_request ワークフローを実行する

branches または branches-ignore フィルターを使って、特定のブランチを対象とする pull request でのみ実行するようにワークフローを構成できます。 詳しくは、「GitHub Actions　のワークフロー構文」を参照してください。

たとえば、このワークフローは、名前が releases/ で始まるブランチを対象とする pull request を誰かが開いたときに実行されます。

on:
  pull_request:
    types:
      - opened
    branches:
      - 'releases/**'

on:
  pull_request:
    types:
      - opened
    branches:
      - 'releases/**'
    paths:
      - '**.js'

(pull request のベース ブランチ名ではなく) pull request の head ブランチ名に基づいてジョブを実行するには、条件で github.head_ref コンテキストを使います。 たとえば、このワークフローは pull request が開かれるたびに実行されますが、pull request の head が releases/ で始まる名前のブランチである場合にのみ run_if ジョブが実行されます。

on:
  pull_request:
    types:
      - opened
jobs:
  run_if:
    if:  startsWith(github.head_ref, 'releases/')
    runs-on: ubuntu-latest
    steps:
      - run: echo "The head of this PR starts with 'releases/'"

pull request で変更されたファイルに基づいて pull_request ワークフローを実行する

また、pull request によって特定のファイルが変更されたときに実行するようにワークフローを構成することもできます。 詳しくは、「GitHub Actions　のワークフロー構文」を参照してください。

たとえば、このワークフローは、pull request に JavaScript ファイル (.js) への変更が含まれているときに実行されます。

on:
  pull_request:
    paths:
      - '**.js'

on:
  pull_request:
    types:
      - opened
    branches:
      - 'releases/**'
    paths:
      - '**.js'

pull request がマージされたときに pull_request ワークフローを実行する

pull request がマージされると、pull request は自動的に閉じられます。 pull request のマージ時にワークフローを実行するには、イベントの merged 値を検査する条件とともにイベントの種類 pull_request``closed を使います。 たとえば、次のワークフローは、pull request が閉じるたびに実行されます。 if_merged ジョブは、pull request もマージされた場合にのみ実行されます。

on:
  pull_request:
    types:
      - closed

jobs:
  if_merged:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
    - run: |
        echo The PR was merged

フォークされたリポジトリのワークフロー

デフォルトでは、フォークされたリポジトリではワークフローは実行されません。 GitHub アクションは、フォークされたリポジトリの [アクション] タブで有効にする必要があります。

GITHUB_TOKEN の例外を除き、ワークフローがフォークされたリポジトリからトリガーされた場合、シークレットはランナーに渡されません。 GITHUB_TOKEN には、フォークされたリポジトリからの pull request での読み取り専用アクセス許可があります。 詳しくは、「自動トークン認証」を参照してください。

フォークしたリポジトリのプルリクエストイベント

フォークされたリポジトリからベースリポジトリへの pull request の場合、GitHub は、ベースリポジトリに pull_request、issue_comment、pull_request_review_comment、pull_request_review、pull_request_target イベントを送信します。 フォークされたリポジトリでは、pull request イベントは発生しません。

初めてのコントリビューターがパブリックリポジトリに pull request をサブミットした場合、書き込み権限を持つメンテナがその pull request に対するワークフローの実行を承認しなければならないことがあります。 詳しくは、「パブリックフォークで実行されるワークフローの実行を承認する」を参照してください。

フォークされたリポジトリからプライベート リポジトリへの pull request の場合、ワークフローは有効になっている場合にのみ実行されます。「リポジトリの GitHub Actions の設定を管理する」を参照してください。

pull_request_comment (issue_comment を使用)

(pull request の差分ではなく) pull request のコメントが作成、編集、または削除されたときにワークフローを実行するには、issue_comment イベントを使います。 pull request レビューまたは pull request レビュー コメントに関連するアクティビティには、pull_request_review または pull_request_review_comment イベントを使います。

pull_request_review

pull request レビューが送信、編集、または無視されたときにワークフローを実行します。 pull request レビューは、本文コメントと状態に加えて、pull request レビュー コメントのグループです。 pull request レビュー コメントまたは pull request コメントに関連するアクティビティには、代わりに pull_request_review_comment または issue_comment イベントを使います。 Pull request レビュー API の詳細については、GraphQL API ドキュメントの「オブジェクト」または「Pull request 用 REST API エンドポイント」を参照してください。

たとえば、pull request レビューが edited または dismissed だったときにワークフローを実行できます。

on:
  pull_request_review:
    types: [edited, dismissed]

pull request が承認されたときにワークフローを実行する

pull request が承認されたときにワークフローを実行するには、種類 submitted の pull_request_review イベントを使ってワークフローをトリガーし、github.event.review.state プロパティを使ってレビューの状態を確認します。 たとえば、このワークフローは pull request レビューが送信されるたびに実行されますが、approved ジョブは、送信されたレビューが承認レビューである場合にのみ実行されます。

on:
  pull_request_review:
    types: [submitted]

jobs:
  approved:
    if: github.event.review.state == 'approved'
    runs-on: ubuntu-latest
    steps:
      - run: echo "This PR was approved"

フォークされたリポジトリのワークフロー

デフォルトでは、フォークされたリポジトリではワークフローは実行されません。 GitHub アクションは、フォークされたリポジトリの [アクション] タブで有効にする必要があります。

GITHUB_TOKEN の例外を除き、ワークフローがフォークされたリポジトリからトリガーされた場合、シークレットはランナーに渡されません。 GITHUB_TOKEN には、フォークされたリポジトリからの pull request での読み取り専用アクセス許可があります。 詳しくは、「自動トークン認証」を参照してください。

フォークしたリポジトリのプルリクエストイベント

フォークされたリポジトリからベースリポジトリへの pull request の場合、GitHub は、ベースリポジトリに pull_request、issue_comment、pull_request_review_comment、pull_request_review、pull_request_target イベントを送信します。 フォークされたリポジトリでは、pull request イベントは発生しません。

初めてのコントリビューターがパブリックリポジトリに pull request をサブミットした場合、書き込み権限を持つメンテナがその pull request に対するワークフローの実行を承認しなければならないことがあります。 詳しくは、「パブリックフォークで実行されるワークフローの実行を承認する」を参照してください。

フォークされたリポジトリからプライベート リポジトリへの pull request の場合、ワークフローは有効になっている場合にのみ実行されます。「リポジトリの GitHub Actions の設定を管理する」を参照してください。

pull_request_review_comment

pull request レビュー コメントが変更されたときにワークフローを実行します。 pull request レビュー コメントは、pull request の差分に関するコメントです。 pull request レビューまたは pull request コメントに関連するアクティビティには、代わりに pull_request_review または issue_comment イベントを使います。 Pull request レビュー コメント API の詳細については、GraphQL API ドキュメントの「オブジェクト」または「Pull request 用 REST API エンドポイント」を参照してください。

たとえば、pull request レビュー コメントが created または deleted だったときにワークフローを実行できます。

on:
  pull_request_review_comment:
    types: [created, deleted]

フォークされたリポジトリのワークフロー

デフォルトでは、フォークされたリポジトリではワークフローは実行されません。 GitHub アクションは、フォークされたリポジトリの [アクション] タブで有効にする必要があります。

GITHUB_TOKEN の例外を除き、ワークフローがフォークされたリポジトリからトリガーされた場合、シークレットはランナーに渡されません。 GITHUB_TOKEN には、フォークされたリポジトリからの pull request での読み取り専用アクセス許可があります。 詳しくは、「自動トークン認証」を参照してください。

フォークしたリポジトリのプルリクエストイベント

フォークされたリポジトリからベースリポジトリへの pull request の場合、GitHub は、ベースリポジトリに pull_request、issue_comment、pull_request_review_comment、pull_request_review、pull_request_target イベントを送信します。 フォークされたリポジトリでは、pull request イベントは発生しません。

初めてのコントリビューターがパブリックリポジトリに pull request をサブミットした場合、書き込み権限を持つメンテナがその pull request に対するワークフローの実行を承認しなければならないことがあります。 詳しくは、「パブリックフォークで実行されるワークフローの実行を承認する」を参照してください。

フォークされたリポジトリからプライベート リポジトリへの pull request の場合、ワークフローは有効になっている場合にのみ実行されます。「リポジトリの GitHub Actions の設定を管理する」を参照してください。

pull_request_target

ワークフローのリポジトリ内の pull request のアクティビティが発生したときにワークフローを実行します。 たとえば、アクティビティの種類が指定されていない場合、pull request を開いたり、再度開いたりしたとき、または pull request の head ブランチが更新されたときにワークフローが実行されます。

このイベントは、pull_request イベントのようにマージ コミットのコンテキストではなく、pull request のベースのコンテキストで実行されます。 これで、リポジトリを変更したり、ワークフローで使うシークレットを盗んだりする可能性がある、pull request の head から安全ではないコードが実行されるのが避けられます。 このイベントを使うと、ワークフローでは、pull request に対するラベルやコメントなどの作業をフォークから行うことができます。 pull request からコードをビルドまたは実行する必要がある場合は、このイベントを使わないでください。

リポジトリのセキュリティを維持するため、特定のパターン (SHA に似ているものなど) と一致する名前を持つブランチからは、pull_request_target イベントでワークフローがトリガーされない場合があります。

たとえば、pull request が assigned、opened、synchronize、または reopened だったときにワークフローを実行できます。

on:
  pull_request_target:
    types: [assigned, opened, synchronize, reopened]

pull request の head またはベース ブランチに基づいて pull_request_target ワークフローを実行する

branches または branches-ignore フィルターを使って、特定のブランチを対象とする pull request でのみ実行するようにワークフローを構成できます。 詳しくは、「GitHub Actions　のワークフロー構文」を参照してください。

たとえば、このワークフローは、名前が releases/ で始まるブランチを対象とする pull request を誰かが開いたときに実行されます。

on:
  pull_request_target:
    types:
      - opened
    branches:
      - 'releases/**'

on:
  pull_request_target:
    types:
      - opened
    branches:
      - 'releases/**'
    paths:
      - '**.js'

(pull request のベース ブランチ名ではなく) pull request の head ブランチ名に基づいてジョブを実行するには、条件で github.head_ref コンテキストを使います。 たとえば、このワークフローは pull request が開かれるたびに実行されますが、pull request の head が releases/ で始まる名前のブランチである場合にのみ run_if ジョブが実行されます。

on:
  pull_request_target:
    types:
      - opened
jobs:
  run_if:
    if:  startsWith(github.head_ref, 'releases/')
    runs-on: ubuntu-latest
    steps:
      - run: echo "The head of this PR starts with 'releases/'"

pull request で変更されたファイルに基づいて pull_request_target ワークフローを実行する

paths または paths-ignore フィルターを使って、pull request によって特定のファイルが変更されたときに実行するようにワークフローを構成することもできます。 詳しくは、「GitHub Actions　のワークフロー構文」を参照してください。

たとえば、このワークフローは、pull request に JavaScript ファイル (.js) への変更が含まれているときに実行されます。

on:
  pull_request_target:
    paths:
      - '**.js'

on:
  pull_request_target:
    types:
      - opened
    branches:
      - 'releases/**'
    paths:
      - '**.js'

pull request がマージされたときに pull_request_target ワークフローを実行する

pull request がマージされると、pull request は自動的に閉じられます。 pull request のマージ時にワークフローを実行するには、イベントの merged 値を検査する条件とともにイベントの種類 pull_request_target``closed を使います。 たとえば、次のワークフローは、pull request が閉じるたびに実行されます。 if_merged ジョブは、pull request もマージされた場合にのみ実行されます。

on:
  pull_request_target:
    types:
      - closed

jobs:
  if_merged:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
    - run: |
        echo The PR was merged

push

コミットまたはタグをプッシュするとき、またはテンプレートからリポジトリを作成するときにワークフローを実行します。

たとえば、push イベントが発生したときにワークフローを実行できます。

on:
  push

特定のブランチへのプッシュが発生した場合にのみワークフローを実行する

branches または branches-ignore フィルターを使って、特定のブランチがプッシュされたときにのみ実行するようにワークフローを構成できます。 詳しくは、「GitHub Actions　のワークフロー構文」を参照してください。

たとえば、このワークフローは、main か、releases/ で始まるブランチに誰かがプッシュしたときに実行されます。

on:
  push:
    branches:
      - 'main'
      - 'releases/**'

on:
  push:
    branches:
      - 'releases/**'
    paths:
      - '**.js'

特定のタグのプッシュが発生した場合にのみワークフローを実行する

tags または tags-ignore フィルターを使って、特定のタグがプッシュされたときにのみ実行するようにワークフローを構成できます。 詳しくは、「GitHub Actions　のワークフロー構文」を参照してください。

たとえば、このワークフローは、v1. で始まるタグを誰かがプッシュしたときに実行されます。

on:
  push:
    tags:
      - v1.**

プッシュが特定のファイルに影響を与える場合にのみワークフローを実行する

paths または paths-ignore フィルターを使って、特定のファイルへのプッシュが発生したときに実行するようにワークフローを構成することができます。 詳しくは、「GitHub Actions　のワークフロー構文」を参照してください。

たとえば、このワークフローは、誰かが JavaScript ファイル (.js) に変更をプッシュしたときに実行されます。

on:
  push:
    paths:
      - '**.js'

on:
  push:
    branches:
      - 'releases/**'
    paths:
      - '**.js'

registry_package

jobs:
    job_name:
        if: $true

GitHub Packages に関連するアクティビティがリポジトリで発生したときにワークフローを実行します。 詳細については、「GitHub Packages のドキュメント」を参照してください。

たとえば、新しいパッケージのバージョンが published になったらワークフローを実行できます。

on:
  registry_package:
    types: [published]

release

リポジトリのリリース アクティビティが発生したときにワークフローを実行します。 リリース API については、GraphQL API ドキュメントの「オブジェクト」または REST API ドキュメントの「リリースとリリース資産の REST API エンドポイント」をご覧ください。

たとえば、リリースが published だったときにワークフローを実行できます。

on:
  release:
    types: [published]

repository_dispatch

GitHub の外部で生じるアクティビティのためにワークフローをトリガーしたい場合、GitHub API を使って、repository_dispatch と呼ばれる Webhook イベントをトリガーできます。 詳しくは、「リポジトリの REST API エンドポイント」を参照してください。

repository_dispatch イベントを作成する要求を行う場合は、アクティビティの種類を説明する event_type を指定する必要があります。 既定では、repository_dispatch のすべてのアクティビティの種類によってワークフローの実行がトリガーされます。 types キーワードを使うと、repository_dispatch Webhook ペイロードで特定の event_type 値が送信されたときに実行されるワークフローを制限できます。

on:
  repository_dispatch:
    types: [test_result]

client_payload パラメーターを使って送信するすべてのデータは、ワークフローの github.event コンテキストで使用できます。 たとえば、リポジトリ ディスパッチ イベントを作成するときにこの要求本文を送信する場合は、次のようになります。

{
  "event_type": "test_result",
  "client_payload": {
    "passed": false,
    "message": "Error: timeout"
  }
}

その後、次のようにワークフロー内のペイロードにアクセスできます。

on:
  repository_dispatch:
    types: [test_result]

jobs:
  run_if_failure:
    if: ${{ !github.event.client_payload.passed }}
    runs-on: ubuntu-latest
    steps:
      - env:
          MESSAGE: ${{ github.event.client_payload.message }}
        run: echo $MESSAGE

schedule

schedule イベントを使うと、スケジュールした時刻にワークフローをトリガーできます。

ワークフローを特定の UTC 時刻に実行するように、POSIX cron 構文でスケジュールすることができます。 スケジュールしたワークフローは、デフォルトまたはベースブランチの直近のコミットで実行されます。 スケジュールされたワークフローを実行できる最短の間隔は、5 分ごとに 1 回です。

この例では、ワークフローは毎日UTCの5:30と17:30にトリガーされます。

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    - cron:  '30 5,17 * * *'

1 つのワークフローを、複数の schedule イベントでトリガーできます。 github.event.schedule のコンテキストを使用して、ワークフローをトリガーしたスケジュール イベントにアクセスできます。 この例では、毎週月曜日から木曜日の 5 時 30 分 (UTC) にワークフローが実行されますが、月曜日と水曜日の Not on Monday or Wednesday 手順はスキップされます。

on:
  schedule:
    - cron: '30 5 * * 1,3'
    - cron: '30 5 * * 2,4'

jobs:
  test_schedule:
    runs-on: ubuntu-latest
    steps:
      - name: Not on Monday or Wednesday
        if: github.event.schedule != '30 5 * * 1,3'
        run: echo "This step will be skipped on Monday and Wednesday"
      - name: Every time
        run: echo "This step will always run"

クーロン構文では、スペースで分けられた 5 つのフィールドがあり、各フィールドは時間の単位を表わします。

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
│ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
│ │ │ │ │
│ │ │ │ │
│ │ │ │ │
* * * * *

5 つのフィールドいずれにおいても、以下の演算子を使用できます:

crontab guru を使うと、cron 構文の生成および実行時間の確認に役立ちます。 作業の開始に役立つ crontab guru のサンプル一覧もあります。

ワークフロー内のクーロン構文を最後に修正したユーザには、スケジュールされたワークフローの通知が送られます。 詳しくは、「ワークフロー実行の通知」を参照してください。

status

Git コミットの状態が変更されたときにワークフローを実行します。 たとえば、コミットは error、failure、pending、または success としてマークできます。 状態の変更に関する詳細を指定する場合は、check_run イベントを使用できます。 コミット状態 API の詳細については、GraphQL API ドキュメントの「オブジェクト」または「コミット用の REST API エンドポイント」を参照してください。

たとえば、status イベントが発生したときにワークフローを実行できます。

on:
  status

新しいコミット状態に基づいてワークフローでジョブを実行する場合は、github.event.state コンテキストを使用できます。 たとえば、次のワークフローはコミット状態が変更されたときにトリガーされますが、if_error_or_failure ジョブは新しいコミット状態が error または failure の場合にのみ実行されます。

on:
  status
jobs:
  if_error_or_failure:
    runs-on: ubuntu-latest
    if: >-
      github.event.state == 'error' ||
      github.event.state == 'failure'
    steps:
      - env:
          DESCRIPTION: ${{ github.event.description }}
        run: |
          echo The status is error or failed: $DESCRIPTION

watch

ワークフローのリポジトリが Star 付きになったときにワークフローを実行します。 pull request API については、GraphQL API ドキュメントの「ミューテーション」または「星付け用 REST API エンドポイント」をご覧ください。

たとえば、誰かがリポジトリに star を付けたときにワークフローを実行できます。これは、Watch イベントのアクティビティの種類 started です。

on:
  watch:
    types: [started]

workflow_call

workflow_call は、別のワークフローからワークフローを呼び出すことができることを示すために使用されます。 workflow_call イベントを使ってワークフローがトリガーされると、呼び出し対象のワークフロー内のイベント ペイロードは、呼び出し元ワークフローからの同じイベント ペイロードになります。 詳しくは、「ワークフローの再利用」をご覧ください。

次の例では、別のワークフローから呼び出された場合にのみワークフローを実行します。

on: workflow_call

workflow_dispatch

ワークフローを手動でトリガーできるようにするには、workflow_dispatch イベントを構成する必要があります。 GitHub API、GitHub CLI、または GitHub ブラウザー インターフェイスを使って、ワークフロー実行を手動でトリガーできます。 詳しくは、「ワークフローの手動実行」を参照してください。

on: workflow_dispatch

入力の提供

カスタム定義の入力プロパティ、デフォルトの入力値、イベントに必要な入力をワークフローで直接設定できます。 イベントをトリガーするときは、ref と任意の inputs を指定できます。 ワークフローを実行すると、inputs コンテキスト内の入力値にアクセスできます。 詳しくは、「ワークフロー実行に関するコンテキスト情報へのアクセス」を参照してください。

この例では、logLevel、tags、environment という名前の入力が定義されています。 これらの入力の値は、ワークフローに実行時に渡します。 次に、このワークフローでは、inputs.logLevel、inputs.tags、inputs.environment のコンテキスト プロパティを使って、値をログに出力します。

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
        type: choice
        options:
        - info
        - warning
        - debug
      tags:
        description: 'Test scenario tags'
        required: false
        type: boolean
      environment:
        description: 'Environment to run tests against'
        type: environment
        required: true

jobs:
  log-the-inputs:
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo "Log level: $LEVEL"
          echo "Tags: $TAGS"
          echo "Environment: $ENVIRONMENT"
        env:
          LEVEL: ${{ inputs.logLevel }}
          TAGS: ${{ inputs.tags }}
          ENVIRONMENT: ${{ inputs.environment }}

ブラウザーからこのワークフローを実行する場合は、ワークフローを実行する前に、必要な入力の値を手動で入力する必要があります。

スクリプトからワークフローを実行するとき、または GitHub CLI を使って、入力を渡すこともできます。 次に例を示します。

gh workflow run run-tests.yml -f logLevel=warning -f tags=false -f environment=staging

詳しくは、「ワークフローの手動実行」で GitHub CLI の情報をご覧ください。

workflow_run

このイベントは、ワークフローの実行が要求されたか完了したときに発生します。 これで、別のワークフローの実行または完了に基づいてワークフローを実行できます。 workflow_run イベントによって開始されたワークフローでは、前のワークフローではできなかった場合でも、シークレットや書き込みトークンにアクセスできます。 これは、以前のワークフローが意図的に権限を与えられていない場合に役立ちますが、権限を与えられたアクションは後のワークフローで行わなければなりません。

この例では、ワークフローは個別の「Run Tests」ワークフローの完了後に実行されるように設定されています。

on:
  workflow_run:
    workflows: [Run Tests]
    types:
      - completed

workflow_run イベントに複数の workflows を指定した場合、実行する必要があるワークフローは 1 つだけです。 たとえば、次のトリガーを持つワークフローは、"ステージング" ワークフローまたは "ラボ" ワークフローが完了するたびに実行されます。

on:
  workflow_run:
    workflows: [Staging, Lab]
    types:
      - completed

別のワークフローの結果に基づいてワークフローを実行する

ワークフロー実行は、前のワークフローの結果に関係なくトリガーされます。 トリガーするワークフローの結果に基づいてジョブまたはステップを実行する場合は、github.event.workflow_run.conclusion プロパティで条件を使用できます。 たとえば、このワークフローは、"Build" という名前のワークフローが完了するたびに実行されますが、on-success ジョブは、"Build" ワークフローが成功した場合にのみ実行され、on-failure ジョブは "Build" ワークフローが失敗した場合にのみ実行されます。

on:
  workflow_run:
    workflows: [Build]
    types: [completed]

jobs:
  on-success:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    steps:
      - run: echo 'The triggering workflow passed'
  on-failure:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    steps:
      - run: echo 'The triggering workflow failed'

ブランチに基づいて実行するワークフローを制限する

branches または branches-ignore フィルターを使って、ワークフローをトリガーするために、トリガーするワークフローで実行する必要があるブランチを指定できます。 詳しくは、「GitHub Actions　のワークフロー構文」を参照してください。 たとえば、次のトリガーを持つワークフローは、名前が canary のブランチで Build という名前のワークフローが実行される場合にのみ実行されます。

on:
  workflow_run:
    workflows: [Build]
    types: [requested]
    branches: [canary]

トリガーするワークフローからデータを使う

ワークフローをトリガーしたワークフローに対応する workflow_runイベント ペイロードにアクセスできます。 たとえば、トリガーするワークフローによって成果物が生成される場合、workflow_run イベントでトリガーされたワークフローからこれらの成果物にアクセスできます。

次のワークフローでは、データを成果物としてアップロードします。 (この簡略化された例では、データは pull request 番号です)。

name: Upload data

on:
  pull_request:

jobs:
  upload:
    runs-on: ubuntu-latest

    steps:
      - name: Save PR number
        env:
          PR_NUMBER: ${{ github.event.number }}
        run: |
          mkdir -p ./pr
          echo $PR_NUMBER > ./pr/pr_number
      - uses: actions/upload-artifact@v4
        with:
          name: pr_number
          path: pr/

上記のワークフローの実行が完了すると、次のワークフローの実行がトリガーされます。 次のワークフローでは、github.event.workflow_run コンテキストと GitHub REST API を使って、上記のワークフローによってアップロードされた成果物をダウンロードします。また、ダウンロードした成果物を解凍し、番号が成果物としてアップロードされた pull request についてコメントします。

name: Use the data

on:
  workflow_run:
    workflows: [Upload data]
    types:
      - completed

jobs:
  download:
    runs-on: ubuntu-latest
    steps:
      - name: 'Download artifact'
        uses: actions/github-script@v6
        with:
          script: |
            let allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({
               owner: context.repo.owner,
               repo: context.repo.repo,
               run_id: context.payload.workflow_run.id,
            });
            let matchArtifact = allArtifacts.data.artifacts.filter((artifact) => {
              return artifact.name == "pr_number"
            })[0];
            let download = await github.rest.actions.downloadArtifact({
               owner: context.repo.owner,
               repo: context.repo.repo,
               artifact_id: matchArtifact.id,
               archive_format: 'zip',
            });
            let fs = require('fs');
            fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/pr_number.zip`, Buffer.from(download.data));

      - name: 'Unzip artifact'
        run: unzip pr_number.zip

      - name: 'Comment on PR'
        uses: actions/github-script@v6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            let fs = require('fs');
            let issue_number = Number(fs.readFileSync('./pr_number'));
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: issue_number,
              body: 'Thank you for the PR!'
            });