GitHub Actions 入門 — ワークフローの基本構文

概要

GitHub Actions は GitHub に統合された CI/CD プラットフォームで、リポジトリへの push や pull request などのイベントをトリガーに、テスト・ビルド・デプロイといった処理を自動化できます。外部の CI サービスを別途契約せず、リポジトリに YAML を1つ追加するだけで動き始めるのが大きな利点です。

本記事では、GitHub Actions のワークフローを構成する最小単位の要素（on / jobs / steps など）をハンズオン形式で組み立てながら、「YAML を見て構造が読める」状態を目標に基本構文を整理します。

環境

• GitHub リポジトリ（public / private いずれも可）
• ワークフローファイルの置き場所: .github/workflows/ 配下
• ファイル形式: YAML（拡張子は .yml または .yaml）
• ランナー: GitHub がホストする ubuntu-latest 等（本記事ではこれを使用）

ワークフローの全体像

まず用語の階層を押さえます。上から順に包含関係になっています。

• Workflow（ワークフロー）: .github/workflows/ に置く YAML ファイル1つ。自動化処理のまとまり
• Event（イベント）: ワークフローを起動するきっかけ（push、pull_request、schedule など）
• Job（ジョブ）: ワークフロー内の実行単位。デフォルトでは並列に走る
• Runner（ランナー）: ジョブを実行する仮想マシン
• Step（ステップ）: ジョブ内で順番に実行される個々の処理
• Action（アクション）: ステップから呼び出す再利用可能な部品

「ワークフロー ⊃ ジョブ ⊃ ステップ」という入れ子を意識すると YAML が読みやすくなります。

最小のワークフローを書く

まずは push のたびに「Hello」と出力するだけの最小構成です。.github/workflows/hello.yml を作成します。

name: Hello Workflow

on: push

jobs:
  say-hello:
    runs-on: ubuntu-latest
    steps:
      - name: Print greeting
        run: echo "Hello, GitHub Actions!"

各キーの役割は次の通りです。

• name: ワークフローの表示名。省略可（省略時はファイルパスが表示される）
• on: トリガーとなるイベント。ここでは push
• jobs: ジョブ定義のマップ。say-hello はジョブ ID（任意の名前）
• runs-on: ジョブを動かすランナーの指定
• steps: 上から順に実行されるステップの配列
• run: シェルコマンドを実行するステップ

この YAML をコミットして push すると、リポジトリの「Actions」タブに実行結果が表示されます。

イベント（on）の書き方

on は書き方が複数あり、条件を絞れます。

単一イベント

on: push

複数イベント

on: [push, pull_request]

ブランチやパスで絞り込む

on:
  push:
    branches:
      - main
      - "release/**"
    paths:
      - "src/**"
  pull_request:
    branches:
      - main

• branches: 対象ブランチを限定。** などのパターンが使える
• paths: 特定のパスに変更があったときだけ起動

定期実行と手動実行

on:
  schedule:
    - cron: "0 0 * * *"   # 毎日 00:00 (UTC) に実行
  workflow_dispatch:        # 手動トリガーを許可

schedule の時刻は UTC 基準である点に注意します。workflow_dispatch を付けると、Actions タブから手動で実行できるようになります。

ジョブとステップを組み立てる

実務でよくある「チェックアウト → セットアップ → テスト」の流れを書いてみます。Node.js プロジェクトを例にします。

name: CI

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

uses と run の違い

• uses: 公開されている アクション を呼び出す。actions/checkout@v4 の @v4 はバージョン指定
• run: 任意のシェルコマンドを実行する

actions/checkout はリポジトリのコードをランナー上に取得するアクションで、ほぼ全てのワークフローの起点になります。with はアクションへ渡す入力パラメータです。

複数ジョブと依存関係（needs）

ジョブは既定で並列に走ります。順序を付けたい場合は needs で依存を宣言します。

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "lint..."

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "test..."

  deploy:
    needs: [lint, test]   # lint と test が両方成功したら実行
    runs-on: ubuntu-latest
    steps:
      - run: echo "deploy..."

この例では lint と test が並列に走り、両方が成功してから deploy が動きます。1つでも失敗すれば deploy はスキップされます。

マトリックスビルド

複数バージョンや複数 OS で同じジョブを回したいときは strategy.matrix を使います。

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: ["18", "20", "22"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test

matrix.node-version に列挙した値の数だけジョブが並列展開されます。${{ ... }} は式（expression）の記法で、コンテキストの値を埋め込むときに使います。

環境変数とシークレット

環境変数は env で定義でき、ワークフロー / ジョブ / ステップの各階層に置けます。

env:
  APP_ENV: production

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      LOG_LEVEL: info
    steps:
      - run: echo "env=$APP_ENV level=$LOG_LEVEL"

API トークンなどの機密値は YAML に直接書かず、リポジトリの Settings → Secrets に登録して secrets コンテキストから参照します。

steps:
  - name: Deploy
    run: ./deploy.sh
    env:
      DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

シークレットはログ出力時に自動的にマスクされますが、そもそも echo などで出力しないのが基本です。

確認方法

1. .github/workflows/ にファイルを追加してコミット・push する
2. リポジトリの Actions タブを開く
3. 対象のワークフロー実行（run）を選び、ジョブ → ステップの順にログを展開する
4. 各ステップの成功（緑）／失敗（赤）と標準出力を確認する

YAML の構文エラーがある場合は、Actions タブ上でパースエラーとして表示されます。ローカルで確認したい場合は YAML リンターや、対応エディタの GitHub Actions 拡張によるスキーマ補完が役立ちます。

注意点

• YAML はインデントに厳格。タブは使えずスペース2つが基本。ネストのずれが最頻出のエラー
• schedule の時刻は UTC。日本時間で考えているとずれる
• アクションのバージョン固定。@v4 のようにメジャーを固定するか、より厳密にコミットハッシュで固定すると再現性・セキュリティ面で安全
• シークレットを run で出力しない。マスクされるとはいえ露出リスクを増やさない
• needs は成功前提。前段が失敗すると後続はスキップされる（if: always() などで制御は可能）

まとめ

GitHub Actions のワークフローは「on（いつ）→ jobs（何を）→ steps（どうやって）」という3階層で読むと構造が掴めます。まずは run で echo するだけの最小ワークフローを1つ動かし、そこから checkout / setup-* アクション、needs による依存、matrix による並列展開へと段階的に広げていくのが習得の近道です。リポジトリ内で完結し追加コストなく試せるので、小さく作って Actions タブでログを見る、を繰り返しながら「読めて直せる」状態を目指しましょう。