GitHub ActionsのWorkFlowに何を書いているのか知りたい

はじめに

すでにある程度環境が整っているプロジェクトに参加すると、

「GitHub に PR を出したら、何かテストやチェックが自動で動いているけど、
正直よく分からない……」

という状態になることがあると思います。

・イメージ（https://github.com/microsoft/vscode ）

本記事では、最小構成のworkflowを題材に、

• GitHub Actions が「どのファイルを」「どの順序で」実行しているのか
• 既存の workflow.yml を 上から順に読むための観点
• 変更してよい箇所／慎重に扱うべき箇所

を整理します。

GitHub Actions が見るファイル

リポジトリ直下の.github/workflows/配下に置いた YAML ファイル（.yml / .yaml）のみが workflow として認識されます。

.github/workflows/*.yml

モノレポ構成で各プロジェクトのフォルダ配下にymlを作っても認識されません。

ワークフローの全体像

GitHub Actionsのworkflowの定義ファイルは、次のような階層構造をしています。

• workflow（ファイル全体）
  • トリガー（on）
  • 共通設定（ env / concurrency等）
  • jobs
    • job
      • job の設定
      • steps
        • step

この記事は階層順に下記のファイルを上から下へ解説します。

name: CI

run-name: Run #${{ github.run_number }} by ${{ github.actor }}

on:  
  push:  
    branches: [main]  
  pull_request:  

env:
  NODE_ENV: test

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:  
  typecheck:  
    runs-on: ubuntu-latest  
    steps:  
      - uses: actions/checkout@v4  
      - uses: actions/setup-node@v4  
        with:  
          node-version: 20  
      - run: npm ci  

name

name: CI

• GitHub Actions の画面に表示される名前
• ymlファイルのファイル名ではなく、ここで定義した名前が表示される

run-name

run-name: Run

• GitHub Actions の「workflow run（実行1回分）」の表示名
• Actionsタブなどでタイトルとして表示される

on

on:  
  push:  
    branches: [main]  
  pull_request:  

• この workflow が動くのかを定義
  • push:branches: [main]
    → main ブランチに push されたときに実行
  • pull_request
    → PR が作成・更新されたときに実行

使用可能なイベントは下記にまとまっています。
https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows

env

env:
  NODE_ENV: test

• GitHub Actionsのworkflow/job/stepで使える環境変数を定義
• key:valueの形で指定

concurrency

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

• 同じ concurrency.group を持つ workflow / job が同時に実行されるのを制御

jobs

jobs:
  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci

• GitHub Actionsにおける実行単位
• job はデフォルトでは並列実行される
• 各 job はそれぞれ独立した runner（実行環境）で実行される
• typecheckはjobの名前

• jobの中で定義できる項目については下記にまとまっています。
  https://docs.github.com/ja/actions/reference/workflows-and-actions/workflow-syntax?utm_source=chatgpt.com#jobs

runs-on

runs-on: ubuntu-latest

• job を動かすrunner（実行環境）を定義

steps

steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci

• stepsはデフォルトでは直列に実行される
• uses
  • 既存の「Action（部品）」を呼び出す際に使用
  • checkout など、よく使われる操作は既製品として定義されており、使用可能
  • 実行環境は Action の実装方法に依存する
• run
  • シェルでコマンドを実行する際に使用
  • jobで指定したrunner上でシェルコマンドとして実行される

終わりに

本記事では、GitHub Actions の workflow.yml について、 実務でよく目にする最小構成をもとに、上から順に読み解いてきました。

他にも定義できる項目は多くあるので、下記を参考にしてみてください。
https://docs.github.com/ja/actions/reference/workflows-and-actions/workflow-syntax