Github Actionsで他リポジトリのワークフローを実行する

こんばんは、情報システム室の夏目です。

個人的に開発しているときに、Githubで別リポジトリのワークフローを実行したくなりました。
別リポジトリのワークフローでトリガーとして workflow_dispatch か repository_dispatch を指定することでできることがわかったので、簡単にまとめたいと思います。

表にしてみる

どちらもREST APIからの実行になります。
そのためGithub Actionsに限らず、どこからもワークフローを実行できます。

選択の上で重要になりそうなのは二つ。

1. 複数のワークフローを同時に実行したいか
   • 一つでよいなら workflow_dispatch, 複数なら repository_dispatch
2. 実行対象のブランチを指定したいか
   • 指定したいなら workflow_dispatch, デフォルトブランチで良いのならどちらでもいい

workflow_dispatch

https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#workflow_dispatch

https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#workflow_dispatch

Github Actionsを手動実行できるようにワークフローのトリガーに設定することが多いですが、1度でも実行したらAPIやCLIから実行できるようになります。

ワークフロー定義サンプル

.github/workflows/workflow_dispatch.yml

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 }}

https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#providing-inputs

別リポジトリ側のワークフロー定義に記載します。

workflow_dispatch では受け取る引数を事前に定義する必要があります。
名前と型を事前定義必要で、必須かオプションか、デフォルト値を設定することも可能です。
定義した値は inputs.<name> という形式で使用可能です。

起動方法

$ curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $YOUR_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/$OWNER/$REPO/actions/workflows/$WORKFLOW_ID/dispatches \
  -d '{
    "ref": "main",
    "inputs": {
      "logLevel": "info",
      "tags": false,
      "environment": "development"
    }
  }'

APIをcurlで叩く場合はこのようになります。

環境変数で指定している値は以下のものです。

• YOUR_TOKEN: GithubのPersonal Access Token (PAT)
  • Repository permissions -> Actions: Read and write の権限が必要
• OWNER: リポジトリのオーナー (Organization名)
• REPO: リポジトリの名前
• WORKFLOW_ID: ワークフローを定義したファイル名

リクエストボディを見るとわかりますが、 ref でワークフローを実行するブランチやタグを指定する必要があります。

ちなみに、Github Actionsからの実行では actions/github-script を使用して実行することもできます。

- uses: actions/github-script@v7
  env:
    OWNER: ${{ vars.OWNER }}
    REPO: ${{ vars.REPO }}
    WORKFLOW_ID: ${{ vars.WORKFLOW_ID }}
  with:
    github-token: ${{ secrets.PAT }}
    script: |
      await github.rest.actions.createWorkflowDispatch({
        owner: process.env.OWNER,
        repo: process.env.REPO,
        workflow_id: process.env.WORKFLOW_ID,
        ref: 'main',
        inputs: {
          logLevel: 'info',
          tags: false,
          environment: 'development'
        }
      });

repository_dispatch

https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#repository_dispatch

https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#repository_dispatch

Github外で発生するイベントをトリガーとしてワークフローを実行する際に使用するトリガーです。
これはGithub外で発生したイベントを元にGithubのAPIをCallしてワークフローを実行するということなので、Github Actions内からもワークフローを実行できます。

ワークフロー定義サンプル

.github/workflows/repository_dispatch.yml

on:
  repository_dispatch:
    types: [test_result]

https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#repository_dispatch

repository_dispatch ではこのように書きます。

types を記載しているとき、API Call時に指定した event_type と一致する場合に実行されます。
types は必須ではないので記載がない場合は、 event_type の値に関わらず常に実行されるようになります。
そのため workflow_dispatch と違い、起動するワークフローが一つとは限りません。
条件を満たすワークフロー全てが実行されます。

workflow_dispatch とのもう一つの違いは inputs の事前定義が必要ないことです。
JSONとして有効なものであれば任意の値を受け取れます。
そのため inputs のバリデーションはワークフロー側で自分で書く必要があります。

起動方法

$ curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $YOUR_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/$OWNER/$REPO/dispatches \
  -d '{
    "event_type": "$EVENT_TYPE",
    "client_payload": {
      "logLevel": "info",
      "tags": false,
      "environment": "production"
    }
  }'

APIをcurlで叩く場合はこのようになります。

環境変数で指定している値は以下のものです。

• YOUR_TOKEN: GithubのPersonal Access Token (PAT)
  • 以下二つの権限が必要
    • Repository permissions -> Contents: Read and write
    • Repository permissions -> Metadata: Read-only (Contents選択で自動選択される)
• OWNER: リポジトリのオーナー (Organization名)
• REPO: リポジトリの名前
• EVENT_TYPE: 任意のイベント名

URLやリクエストボディを見るとわかりますが、 workflow_dispatch と異なり ref がありません。
repository_dispatch では常にデフォルトブランチのワークフローファイルを使用します。

こちらも actions/github-script で書くと次のようになります。

- uses: actions/github-script@v7
  env:
    OWNER: ${{ vars.OWNER }}
    REPO: ${{ vars.REPO }}
    EVENT_TYPE: ${{ vars.EVENT_TYPE }}
  with:
    github-token: ${{ secrets.YOUR_TOKEN }}
    script: |
      await github.rest.actions.createDispatchEvent({
        owner: process.env.OWNER,
        repo: process.env.REPO,
        event_type: process.env.EVENT_TYPE,
        client_payload: {
          logLevel: 'info',
          tags: false,
          environment: 'development'
        }
      });

まとめ

以上、 workflow_dispatch と repository_dispatch について簡単にまとめました。

何かの役に立てたら幸いです。