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

2023-04-262023-04-30Git,GitHub,Github Actions

はじめに

前回は 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 ワークスペースを作成します。

$ 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.yaml

YAML ファイルの内容は以下のようになります。
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-actions

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

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

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

run-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 ジョブ内で実行される全ステップとなります。

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

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

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 bats

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

- run: bats -v

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

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

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

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

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

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

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

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

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

ひとこと

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