GitHub Actions の基本(メモ)

構成要素の概要

階層構造

  • Workflow
  • Job (実行単位)
    • Step (処理単位)

Workflow

  • トリガーによりキックされる単位
  • 何をトリガーに実行するかは on: で指定

Job

  • Workflow の構成要素、Runner により実行される単位
  • どの Runner で実行するかは runs-on: で実行する (GitHub ホストランナー)
  • セルフホストの場合は runs-on: self-hosted
  • container: を指定すると任意の Docker イメージのコンテナ上で実行される (未指定時は Runner 上で直接実行)
  • Docker Hub のイメージのみ?
  • needs: で他の Job との依存関係を指定することで、直列化や並列化
  • if: で実行条件を指定
  • Jobs 間で環境は引き継がれない (毎回初期化される)
  • ★self-hosted の場合? 前回の環境が残ってしまうので最初に削除するようにしたほうが良さそう
  • Job 間で結果の受け渡しをする場合は outputs:, inputs: を使う
  • ★self-hosted の場合? sudo で root になるとインストールなど何でもできる気がするので注意

Step

  • Job の構成要素
  • 記述順に従って実行される
  • run: で任意のコマンド、または uses: で Actions を実行する
  • if: で実行条件を指定
  • 環境変数は特定のもののみ引き継がれる (export しただけでは引き継がれない)

Action

  • runs: で実行環境を指定
  • using: docker + image: を指定するとコンテナ上で実行
  • input: で設定値を渡す
  • 特定の環境変数は引き継がれる
  • docker run でコンテナを起動すると Runner の Dockerd が使われる (Docker outside of Docker)
  • ★が、ボリュームマウントしてもソースファイルが見えない。

トリガーの指定

参照) Events that trigger workflows - GitHub Docs

Workflow をキックするトリガーを on: で指定する。

  • schedule:
  • push: : push されたとき / マージされたとき
  • pull_request: : PR されたとき (PR が更新されたとき)
  • workflow_dispatch: : 手動で任意のタイミングで実行できるようにする
  • workflow_call: : 他の Workflow から呼び出せるようにする (Reusable Workflow)
  • repository_dispatch: : 外部から API で実行できるようにする

Job の実行順

needs: で依存する job を指定する(指定がない場合は異なる Runner で並列に実行される)。needs.(job名).result で job の結果によって分岐できる。

例) job1 が終わったら job2 を実行する場合。

job2:
  needs: job1
  if: ${{ needs.job1.result == 'success' }}

Contexts

参照) Contexts - GitHub Docs

Workflow が実行された情報を Step 内で展開して使用することができる。

  • ${{ runner.os }} : Runner の OS 名
  • ${{ runner.arch }} : Runner のアーキテクチャ
  • ${{ github.server_url }} : GitHub サーバーの URL (パスなし)
  • ${{ github.repository }} : リポジトリ名 (organization/repository)
  • ${{ github.run_id }} : リポジトリごとの Workflow 実行番号
  • ${{ github.ref_type }} : トリガーのタイプ (branch/tag)
  • ${{ github.ref_name }} : トリガーとなったブランチまたはタグ名 (ref_type による)
  • ${{ github.sha }} : トリガーとなったコミットの HASH

Environment variables (環境変数)

参照) Environment variables - GitHub Docs

環境変数で参照できる情報もある。

  • GITHUB_EVENT_PATH : リクエストペイロード(JSON)が保存されたファイルのパス
  • GITHUB_ENV : Step 間で引き継ぎたい環境変数を保存するためのパス。用意された環境変数意外を直接設定して次の Step に引き継ぐことはできないため、これを利用する。

環境変数は Contexts から参照することもできる。

  • ${{ env.XXXX }}

Expressions

参照) Expressions - GitHub Docs

条件分岐や計算による値を使用することができる。

  • ${{ always() }} : 常に true
  • ${{ hashFiles(ファイル名) }} : ファイルのハッシュ値を取得

公開変数

steps 間で値を受け渡す場合に使用する。

  • 保存) ::set-output name=(変数名)::(値)
  • 参照) ${{ steps.(step_id).outputs.(変数名) }}

Actions の利用

Caching (actions/cache)

参考) Cache - Marketplace

  • 一時的なキャッシュを Workflow 間で共有
  • 次の Workflow 実行時に持ち越すことができる

例)

- uses: actions/cache@v3
  with:
    key: vendor-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('composer.lock') }}
    path: vendor
  • この step で(キャッシュがあれば)復元し、job が完了した時点のものをキャッシュする
  • path : キャッシュ対象のディレクトリ/ファイル
  • key : キャッシュキー。例のように hashFiles() を使ってファイルのハッシュ値を key に使うことで、そのファイルが変更されていなければキャッシュを使い、変更された場合はキャッシュを使わないようにできる

Artifact (actions/upload-artifact, actions/download-artifact)

参考) Upload a Build Artifact - Marketplace / Download artifact - Marketplace

  • 成果物を永続化する
  • Actions の実行履歴からダウンロードできる

その他