GitHub Actions 講座 #1 ワークフローの構造 — イベント、ジョブ、ランナー、初めての実行
コードをプッシュするたびにローカルでテストを回し、レビュアーは「テストは実行しましたか」と尋ね、リリースの日には誰かがビルドコマンドを順番に打ちます。この繰り返しを人間がやっている限り、いつか抜け落ちる日が来て、その日に限って事故が起きます。リポジトリでイベント(プッシュ、PR 作成など)が起きたら指定した処理を自動で実行してくれる道具が GitHub Actions で、GitHub にリポジトリがあれば追加のインストールなしにすぐ使えるため、CI/CD の事実上のデフォルトになりました。このシリーズは最初のワークフローから、組織単位の再利用、セキュリティ、運用パターンまでを 10 本で扱います。今回の目標は、構造を成す 5 つの概念をつかんで最初のワークフローを実行してみることです。
5 つの概念 — ワークフロー、イベント、ジョブ、ステップ、ランナー #
GitHub Actions のすべては 5 つの単語で説明できます。
イベント(push、PR、...)が起きると
→ ワークフロー(.github/workflows/*.yml)が起動し
→ ワークフロー内のジョブ(job)がそれぞれのランナー(仮想マシン)で実行され
→ ジョブはステップ(step)を上から下へ順番に実行します- ワークフロー(workflow): 自動化ひとまとまりの定義です。リポジトリの
.github/workflows/ディレクトリに YAML ファイルとして置きます。このパスは決まりごとで、変更できません。 - イベント(event): ワークフローを起動させるきっかけです。プッシュ、PR、予約時刻、手動ボタンなど数十種類あります。
- ジョブ(job): 実行の単位です。1 つのワークフローに複数のジョブを置け、デフォルトでは互いに並列で動きます。
- ステップ(step): ジョブの中の一行一行です。シェルコマンド(
run)か、誰かが作っておいたアクション(uses)です。 - ランナー(runner): ジョブが実行されるマシンです。GitHub が提供する仮想マシンを使うのが基本です。
最初のワークフロー — プッシュのたびにテストを実行 #
Python プロジェクトにテスト自動化を付けてみます。リポジトリにファイルを 1 つ追加するだけです。
# .github/workflows/test.yml
name: test
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.13"
- run: pip install -r requirements.txt
- run: pytest先ほどの 5 つの概念がすべて入っています。on がイベント(main へのプッシュとすべての PR)、jobs.test がジョブ 1 つ、runs-on がランナーの指定、steps の 4 行がステップです。初めて見るのは uses で呼び出すアクションです。actions/checkout はランナーにリポジトリのコードをダウンロードするアクションで、actions/setup-python は Python をインストールするアクションです。ランナーは毎回まっさらなマシンとして始まるので「コードを取得する」ところからが利用者側の仕事になるのですが、こうした繰り返し作業をパッケージにしておいた部品がアクションで、マーケットプレイスに数万個が公開されています。@v4 のような接尾辞はアクションのバージョン指定で、詳しい文法と安全な固定方法はそれぞれ次回と #9 で扱います。
このファイルをコミットしてプッシュすると、そのプッシュからワークフローが動きます。別途の登録手続きがない、つまりワークフローファイルの存在そのものが登録だという点が、GitHub Actions の敷居を下げている特徴です。
実行結果の読み方 — Actions タブ #
プッシュ直後、リポジトリの Actions タブに実行が現れます。読む順番は実行一覧 → ジョブ → ステップです。失敗すると失敗したステップが自動で展開されてログを見せてくれ、PR 画面にもチェック結果が表示されるので、レビュアーが「テストは実行しましたか」と尋ねる必要がなくなります。README にステータスバッジを付ければ、リポジトリのトップページで最新の実行状態が見えます。
イベントは push だけではありません #
on に書ける代表的なイベントを先に眺めておくと、シリーズ全体の地図になります。
| イベント | 起動するタイミング | 代表的な用途 |
|---|---|---|
push | ブランチへのプッシュ | テスト、ビルド |
pull_request | PR の作成・更新 | レビュー前の検証 |
schedule | cron の予約時刻 | 夜間チェック、定期作業 |
workflow_dispatch | 人がボタンをクリック | 手動デプロイ、単発作業 |
release | リリースの発行 | パッケージ配布 |
schedule と workflow_dispatch は、リポジトリのイベントがなくても実行できるという意味で、GitHub Actions を CI を超えた汎用自動化ツールにしてくれる部品です。イベントに条件(特定のパス、特定のブランチ)を付けて精密に起動する方法は、次回の文法で扱います。
ランナーと料金の常識 #
runs-on: ubuntu-latest は GitHub がホスティングする Ubuntu 仮想マシンを意味し、macOS と Windows のランナーもあります。料金はアカウントの種類によって異なります。パブリックリポジトリでは GitHub ホステッドランナーが無料で、プライベートリポジトリは月の無料枠(プランごとに異なる)を超えた分から分単位の課金になり、macOS ランナーは Linux より倍率が高くなります。正確な枠と単価は変動があるので料金ドキュメントの確認を前提にしつつ、「プライベートリポジトリの macOS ジョブは高い」という感覚だけは今持って帰ってください。コストを下げるキャッシュ戦略とセルフホステッドランナーは、それぞれ #4 と #8 のテーマです。
まとめ #
今回扱った内容です。
- GitHub Actions はイベント → ワークフロー → ジョブ → ステップの構造で、ジョブはランナーというまっさらな仮想マシンで実行されます
- ワークフローは
.github/workflows/の YAML ファイルで、ファイルの存在がそのまま登録です - ランナーは毎回初期状態なので checkout から始まり、繰り返し作業はマーケットプレイスのアクションで処理します
- イベントは push、pull_request のほかに schedule と workflow_dispatch があり、汎用自動化までカバーします
- パブリックリポジトリはランナーが無料、プライベートは無料枠を超えた分が分単位の課金です
次回(#2 文法の核心)では、今日は駆け足で通り過ぎた YAML の文法をきちんと押さえます。ステップ間で値をやり取りするコンテキストと式、if 条件でステップを選んで実行する方法です。