Github Actions入門その2-簡単なワークフローを作成してみる

はじめに

前回は Github Actions の概要と用語の整理をしました。

Github Actions 入門その 1-概要と用語の整理 | ゲンゾウ用ポストイット

Github 上で実行できるワークフローを構築するためのサービスです。 Github 上でのソースコードの変更をトリガーにして、自動的にビルドやテストなどのワークフローを実行できます。 Unbutu、Windows、macOS などの環境で実行でき、必要なリソースを設定することで、ビルドなどのタスクを実行できます。

今回は、サンプルコードを触って Github Actions を実際に操作してみます。

簡単なワークフローを作成してみる

Github Actions では、ワークフローの設定を YAML 形式で記述します。

それぞれのワークフローは YAML 形式のファイル 1 つで表現されます。その YAML をワークフローを実行させたい Github リポジトリの .github/workflows というディレクトリに配置します。

ワークフローは、トリガーとなるイベント ( 例えば git push ) が発生したタイミングで実行されます。

ここからは実際にワークフロー設定ファイルを見ていきます。

以下のようなワークフローを作成してみます。

プッシュのタイミングで実行される
Node.js のツールである bats をインストールする
bats -v コマンドを実行する

まずはローカルに Git ワークスペースを作成します。

1
2
3
4
5
$ mkdir learning-github-actions

$ cd learning-github-actions

$ git init

対応する Git リモートリポジトリを作成します。ここでは Github CLI ( gh コマンド) を使って作成しますが、もちろんブラウザ経由で作成しても構いません。

1
2
3
$ 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 が好みです。

1
2
3
4
5
6
$ mkdir -p .github/workflows/

$ touch .github/workflows/learn-github-actions.yaml

# 好きなエディタで開く
$ vi .github/workflows/learn-github-actions.yaml

YAML ファイルの内容は以下のようになります。 YAML ファイルの各行の設定内容については、後述します 。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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

あとはファイルをコミットし、リモートリポジトリにプッシュします。

1
2
3
4
5
6
7
8
$ 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 サブコマンドに様々なサブコマンド、オプションが用意されています。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
# 実行されたワークフローを一覧表示
$ 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 形式の設定ファイルの各行について、細かく見ていきます。

1
name: learn-github-actions

name は任意属性です。設定しなくても問題ありません。文字通り、ワークフロー名になります。

省略すると、Github ページのワークフロー名はファイル名になります。

1
run-name: ${{ github.actor }} is learning Github Actions

run-name は任意属性です。

実行されたワークフローの名前となります。

省略すると、Github ページの実行されたワークフロー名はコミットメッセージになります。

ちなみに、ここでは github.actor という情報を出力するための評価式を使っています。実行時に ${{ github.actor }} の部分はワークフロー実行者の名前で置き換えられます。

1
2
on:
  - push

必須属性です。

ワークフロー起動のトリガーとなる「イベント」を１つ以上指定します。複数指定可能です。

ここでは push イベントをトリガーとするようにしています。 git push タイミングだけでなく、プルリクエストをマージしたときにも push イベントは発生します。また、すべてのブランチに対するプッシュ操作でイベントが発生します。

更に push イベントの対象を絞ることもできます。例えば特定のブランチだけを対象としたり、特定のファイルやディレクトリだけを対象とすることもできます。

以下のように設定することでスケジュール起動もできます。

1
2
3
on:
  schedule:
    - cron: "30 5,17 * * *"

1
jobs:

必須属性です。

実行されるジョブのセットです。

複数指定可能ですが、ここでは１つだけ設定しました。

1
check-bats-version:

ジョブ名を設定します。ここは、予約後ではなく任意に設定可能な文字列となります。

ここからインデントされた YAML 設定情報はすべて、ジョブに関する設定となります。

1
runs-on: ubuntu-22.04

必須属性です。

ジョブを実行する仮想環境を指定します。ここでは Github 内の Ubuntu Linux 22.04 の仮想マシンでジョブを実行するように指定しています。

1
steps:

必須属性です。

check-bats-version ジョブ内で実行される全ステップとなります。

ワークフロー、ジョブ、ステップの関係を忘れてしまったときは以下を参照ください。

Github Actions 入門その 1-概要と用語の整理 | ゲンゾウ用ポストイット

steps 以下には、配列要素を指定します。要素は action または shellscript のいずれかになります。

1
- uses: actions/checkout@v3

このステップでは、uses キーワードは「アクション」を利用することを表しています。

ここでは actions/checkout アクションの v3 バージョンを実行します。これは、Git リポジトリの内容をチェックアウトするアクションとなります。

ほとんどのワークフロー設定ファイルで利用されると思います。

1
2
3
- uses: actions/setup-node@v3
  with:
    node-version: "14"

このステップでは、 actions/setup-node@v3 アクションを使用して Node.js をインストールしています。バージョンは v14 を指定しています。結果、 PATH 環境変数の通ったディレクトリに node と npm コマンドが置かれます。

1
- run: npm install -g bats

run はジョブに指定したコマンドの実行を指示するキーワードです。このケースでは npm コマンドを使って bats をインストールしています。

1
- run: bats -v

最後に、 bats コマンドを -v オプション付きで実行し、バージョンを表示します。

起動済みワークフローの設定を視覚化する

Github Actions では、ワークフローの設定を YAML 形式で記述します。

YAML 形式の設定ファイルを見ていると、ワークフローの詳細がわかりづらい場合があります。

そこで、Github Actions では、「起動済みワークフロー」を視覚化する機能を提供しています。

ここで「起動済みワークフロー」と書いているのは、ドキュメントでは “a workflow run” と書かれています。ワークフローの設定内容をもとに実際にイベントによりトリガーされたワークフローのことを「起動済みワークフロー」と訳してみました。

起動済みワークフローは、ジョブの関係（グラフ）を視覚化して見ることができます。

https://github.com/ にて、該当のリポジトリページを開く
Actions タブを開く
左サイドバーから、確認したいワークフロー名をクリック
起動済みのワークフローが一覧表示されているので、名前をクリック

今回作成したワークフローがあまりにシンプルなので、トリガーとなったイベントと 1 つのジョブしか表示されていませんが、複数のジョブが直列に実行された、並列に実行されたなどが確認できるページとなっています。

ひとこと

Github Actions 入門その 1-概要と用語の整理 | ゲンゾウ用ポストイットに続き、各用語と実際の YAML 設定ファイルの項目の対応が理解できたと思います。