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

完了

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

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

前述のように、GitHub で特定のアクティビティが発生したとき、GitHub の外部のイベントが発生したとき、またはスケジュールされた時刻に実行するように、ワークフローを構成できます。 POSIX cron 構文を使用して、scheduleイベントにより、特定の UTC 時刻に実行するワークフローをトリガーできます。 この cron 構文には 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]

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

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

たとえば、ワークフローの次のステップに進むために、github.ref (ワークフローの実行をトリガーしたブランチまたはタグ参照) が refs/heads/main に一致するかどうかをチェックする if 条件を使用するワークフローは、次のようになります。

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 UI の [アクション] タブから、または GitHub API エンドポイント DELETE /repos/{owner}/{repo}/actions/runs/{run_id} を使用して、進行中のワークフロー実行を取り消すこともできます。 ワークフローの実行を取り消すと、GitHub によって、その実行内のすべてのジョブとステップが取り消されることに注意してください。

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

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

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

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

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

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 を使用することが推奨されます。