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 の実行履歴からダウンロードできる