Github Actions入門その2-簡単なワークフローを作成してみる
はじめに
前回は Github Actions の概要と用語の整理をしました。
Github 上で実行できるワークフローを構築するためのサービスです。
Github 上でのソースコードの変更をトリガーにして、自動的にビルドやテストなどのワークフローを実行できます。
Unbutu、Windows、macOS などの環境で実行でき、必要なリソースを設定することで、ビルドなどのタスクを実行できます。
今回は、サンプルコードを触って Github Actions を実際に操作してみます。
簡単なワークフローを作成してみる
Github Actions では、ワークフローの設定を YAML 形式で記述します。
それぞれのワークフローは YAML 形式のファイル 1 つで表現されます。
その YAML をワークフローを実行させたい Github リポジトリの .github/workflows というディレクトリに配置します。
ワークフローは、トリガーとなるイベント ( 例えば git push ) が発生したタイミングで実行されます。
ここからは実際にワークフロー設定ファイルを見ていきます。
以下のようなワークフローを作成してみます。
- プッシュのタイミングで実行される
- Node.js のツールである
batsをインストールする bats -vコマンドを実行する
まずはローカルに Git ワークスペースを作成します。
$ mkdir learning-github-actions
$ cd learning-github-actions
$ git init対応する Git リモートリポジトリを作成します。
ここでは Github CLI ( gh コマンド) を使って作成しますが、もちろんブラウザ経由で作成しても構いません。
$ gh repo create --public --source=. --remote=origin
✓ Created repository genzouw/learning-github-actions on GitHub
✓ Added remote https://github.com/genzouw/learning-github-actions.git.github/workflows/ ディレクトリ配下に learn-github-actions.yaml というファイルを作成します。
拡張子は yml または yaml が使われますが、僕は yaml が好みです。
$ mkdir -p .github/workflows/
$ touch .github/workflows/learn-github-actions.yaml
# 好きなエディタで開く
$ vi .github/workflows/learn-github-actions.yamlYAML ファイルの内容は以下のようになります。
YAML ファイルの各行の設定内容については、後述します 。
name: learn-github-actions
run-name: ${{ github.actor }} is learning Github Actions
on:
- push
jobs:
check-bats-version:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: "14"
- run: npm install -g bats
- run: bats -vあとはファイルをコミットし、リモートリポジトリにプッシュします。
$ git add .github/workflows/learn-github-actions.yaml
$ git commit -m "first commit."
[main (root-commit) 8afb782] first commit.
1 file changed, 14 insertions(+)
create mode 100644 .github/workflows/learn-github-actions.yaml
$ git pushブラウザで該当の Github リポジトリページから、Actions タブを開くと実行された Github Actions が確認できます。
( リモートリポジトリへの初めての push のはずですが、なぜか 2 回実行されています。
)
実行されたワークフローの名前をクリックすると、詳細が確認できます。
設定したとおり、 bats -v コマンドが正常に実行できています。
実行結果は Github CLI ( gh コマンド) を使っても確認できます。gh run サブコマンドに様々なサブコマンド、オプションが用意されています。
# 実行されたワークフローを一覧表示
$ gh run list
STATUS TITLE WORKFLOW BRANCH EVENT ID ELAPSED AGE
✓ genzouw is learning Github Actions learn-github-actions main push 4791647631 13s 0m
✓ genzouw is learning Github Actions learn-github-actions main push 4791647538 18s 0m
# ID を指定すると、中のジョブが確認できる
$ gh run view 4791647631
✓ main learn-github-actions · 4791647631
Triggered via push about 1 minute ago
JOBS
✓ check-bats-version in 4s (ID 12990425065)
For more information about the job, try: gh run view --job=12990425065
View this run on GitHub: https://github.com/genzouw/learning-github-actions/actions/runs/4791647631
# ジョブID を指定すると、中のステップが確認できる
$ gh run view --job=12990425065
✓ main learn-github-actions · 4791647631
Triggered via push about 2 minutes ago
✓ check-bats-version in 4s (ID 12990425065)
✓ Set up job
✓ Run actions/checkout@v3
✓ Run actions/setup-node@v3
✓ Run npm install -g bats
✓ Run bats -v
✓ Post Run actions/setup-node@v3
✓ Post Run actions/checkout@v3
✓ Complete job
To see the full job log, try: gh run view --log --job=12990425065
View this run on GitHub: https://github.com/genzouw/learning-github-actions/actions/runs/4791647631
# --log オプション付きでログが確認できます。長いので一部抜粋。
$ gh run view --log --job=12990425065
...
check-bats-version Run bats -v 2023-04-24T22:27:08.2401411Z ##[group]Run bats -v
check-bats-version Run bats -v 2023-04-24T22:27:08.2401648Z bats -v
check-bats-version Run bats -v 2023-04-24T22:27:08.2455194Z shell: /usr/bin/bash -e {0}
check-bats-version Run bats -v 2023-04-24T22:27:08.2455446Z ##[endgroup]
check-bats-version Run bats -v 2023-04-24T22:27:08.2635263Z Bats 1.9.0
...gh run view --log コマンドの最後に指定するのは、ジョブ ID ではなく実行されたワークフロー ID でも構いません。
以降、プッシュ操作が行われるとこのワークフローが実行されるようになります。
ワークフロー設定ファイルを細かく見ていく
YAML 形式の設定ファイルの各行について、細かく見ていきます。
name: learn-github-actionsname は任意属性です。
設定しなくても問題ありません。
文字通り、ワークフロー名になります。
省略すると、Github ページのワークフロー名はファイル名になります。
run-name: ${{ github.actor }} is learning Github Actionsrun-name は任意属性です。
実行されたワークフローの名前となります。
省略すると、Github ページの実行されたワークフロー名はコミットメッセージになります。
ちなみに、ここでは github.actor という情報を出力するための評価式を使っています。
実行時に ${{ github.actor }} の部分はワークフロー実行者の名前で置き換えられます。
on:
- push必須属性です。
ワークフロー起動のトリガーとなる「イベント」を１つ以上指定します。
複数指定可能です。
ここでは push イベントをトリガーとするようにしています。git push タイミングだけでなく、プルリクエストをマージしたときにも push イベントは発生します。
また、すべてのブランチに対するプッシュ操作でイベントが発生します。
更に push イベントの対象を絞ることもできます。
例えば特定のブランチだけを対象としたり、特定のファイルやディレクトリだけを対象とすることもできます。
以下のように設定することでスケジュール起動もできます。
on:
schedule:
- cron: "30 5,17 * * *"jobs:必須属性です。
実行されるジョブのセットです。
複数指定可能ですが、ここでは１つだけ設定しました。
check-bats-version:ジョブ名を設定します。
ここは、予約後ではなく任意に設定可能な文字列となります。
ここからインデントされた YAML 設定情報はすべて、ジョブに関する設定となります。
runs-on: ubuntu-22.04必須属性です。
ジョブを実行する仮想環境を指定します。
ここでは Github 内の Ubuntu Linux 22.04 の仮想マシンでジョブを実行するように指定しています。
steps:必須属性です。
check-bats-version ジョブ内で実行される全ステップとなります。
ワークフロー、ジョブ、ステップの関係を忘れてしまったときは以下を参照ください。
steps 以下には、配列要素を指定します。
要素は action または shellscript のいずれかになります。
- uses: actions/checkout@v3このステップでは、uses キーワードは「アクション」を利用することを表しています。
ここでは actions/checkout アクションの v3 バージョンを実行します。
これは、Git リポジトリの内容をチェックアウトするアクションとなります。
ほとんどのワークフロー設定ファイルで利用されると思います。
- uses: actions/setup-node@v3
with:
node-version: "14"このステップでは、 actions/setup-node@v3 アクションを使用して Node.js をインストールしています。
バージョンは v14 を指定しています。
結果、 PATH 環境変数の通ったディレクトリに node と npm コマンドが置かれます。
- run: npm install -g batsrun はジョブに指定したコマンドの実行を指示するキーワードです。
このケースでは npm コマンドを使って bats をインストールしています。
- run: bats -v最後に、 bats コマンドを -v オプション付きで実行し、バージョンを表示します。
起動済みワークフローの設定を視覚化する
Github Actions では、ワークフローの設定を YAML 形式で記述します。
YAML 形式の設定ファイルを見ていると、ワークフローの詳細がわかりづらい場合があります。
そこで、Github Actions では、「起動済みワークフロー」を視覚化する機能を提供しています。
ここで「起動済みワークフロー」と書いているのは、ドキュメントでは "a workflow run" と書かれています。
ワークフローの設定内容をもとに実際にイベントによりトリガーされたワークフローのことを「起動済みワークフロー」と訳してみました。
起動済みワークフローは、ジョブの関係（グラフ）を視覚化して見ることができます。
- https://github.com/ にて、 該当のリポジトリページを開く
- Actions タブを開く
- 左サイドバーから、確認したいワークフロー名をクリック
- 起動済みのワークフローが一覧表示されているので、名前をクリック
今回作成したワークフローがあまりにシンプルなので、トリガーとなったイベントと 1 つのジョブしか表示されていませんが、複数のジョブが直列に実行された、並列に実行されたなどが確認できるページとなっています。
ひとこと
Github Actions 入門その 1-概要と用語の整理 | ゲンゾウ用ポストイット に続き、各用語と実際の YAML 設定ファイルの項目の対応が理解できたと思います。