GitHub Actions は、リポジトリに YAML ファイルを1つ置くだけで、push やプルリクエストのたびにテストやチェックを自動で動かせる仕組みです。この記事では、ワークフローファイルの置き場所と基本構文を押さえたうえで、WordPress のプラグインやテーマを想定した「PHP の構文チェック」を自動で走らせる最初のワークフローを作ります。失敗したときのログの読み方と、初心者がつまずきやすい点もあわせて説明します。
デプロイまで含めたパイプラインの組み方は、続編の「CI/CDパイプラインを構築」の記事で扱います。本記事は「ワークフローとは何か」と「最初の1本を動かす」ことに絞っています。
GitHub Actions の基本用語
最初に、YAML に出てくる言葉の関係を整理しておきます。
- ワークフロー（workflow）: 自動化の単位です。
.github/workflows/ディレクトリに置いた1つの YAML ファイルが1つのワークフローになります。 - イベント（on）: ワークフローを動かすきっかけです。
push、pull_request、手動実行のworkflow_dispatch、定期実行のscheduleなどがあります。 - ジョブ（jobs）: ワークフローの中の処理のまとまりです。ジョブごとに新しい仮想マシン（ランナー）が用意され、複数のジョブは特に指定しなければ並列に動きます。
- ステップ（steps）: ジョブの中で上から順に実行される1つ1つの処理です。シェルコマンドを書く
runと、公開されている部品（アクション）を呼び出すusesの2種類があります。 - ランナー（runs-on）: ジョブを実行する環境です。GitHub が用意する
ubuntu-latestなどを指定するのが一般的で、自前のサーバーを登録するセルフホストランナーも使えます。
公開リポジトリと非公開リポジトリでは、GitHub ホストのランナーを使える時間の扱いが異なります。無料枠や課金の条件はプランによって変わるため、利用前に GitHub の公式ドキュメントで確認してください（2026年10月現在）。
最初のワークフローを作る
リポジトリのルートに .github/workflows/php-lint.yml を作ります。ディレクトリ名は .github（先頭にドット）、その下が workflows（複数形）です。ここを間違えるとワークフローとして認識されません。
name: PHP Lint
on:
push:
branches: [ main ]
pull_request:
workflow_dispatch:
permissions:
contents: read
jobs:
lint:
runs-on: ubuntu-latest
steps:
- name: リポジトリを取得
uses: actions/checkout@v4
- name: PHP をセットアップ
uses: shivammathur/setup-php@v2
with:
php-version: '8.2'
tools: none
- name: PHP の構文チェック
run: |
find . -name '*.php' -not -path './vendor/*' -not -path './node_modules/*' -print0 \
| xargs -0 -n1 php -l上から順に意味を見ていきます。
on では、main ブランチへの push、すべてのプルリクエスト、手動実行の3つをきっかけにしています。workflow_dispatch を入れておくと、リポジトリの Actions タブからボタンで実行できるので、動作確認に便利です。
permissions は、ワークフロー内で自動的に発行される GITHUB_TOKEN に与える権限です。チェックするだけならリポジトリの読み取りで足りるので contents: read に絞っています。必要最小限の権限にしておくと、万一サードパーティのアクションに問題があった場合の影響を小さくできます。
steps の最初の actions/checkout は、ランナーにリポジトリのコードを取得するアクションです。ランナーは毎回まっさらな状態で起動するため、これがないとコードが1行もありません。「ファイルが見つからない」というエラーの多くは、このステップの書き忘れが原因です。
shivammathur/setup-php は、指定したバージョンの PHP をランナーに用意する、広く使われているアクションです。プラグインがサポートする PHP のバージョンに合わせて php-version を変えてください。
最後の run では、vendor と node_modules を除いたすべての PHP ファイルに php -l（構文チェック）を実行しています。1ファイルでも構文エラーがあればコマンドが失敗し、ジョブが赤く表示されます。
アクションの @v4 や @v2 はメジャーバージョンの指定です。新しいメジャーバージョンが出ることがあるため、各アクションのリポジトリで最新の推奨バージョンを確認してから使ってください。
動かして結果を確認する
ファイルをコミットして main に push すると、リポジトリの Actions タブにワークフローの実行が表示されます。黄色の丸が実行中、緑のチェックが成功、赤のバツが失敗です。
失敗したときは、実行結果からジョブを開き、赤くなっているステップを展開するとログが読めます。PHP の構文エラーなら、PHP Parse error: syntax error, unexpected ... in ./includes/class-foo.php on line 42 のように、ファイル名と行番号が出ています。手元で同じファイルを php -l にかければ再現できるはずです。
ログだけでは原因が分からないときは、失敗した実行をデバッグログ付きで再実行する機能があります。また、リポジトリのシークレットか変数に ACTIONS_STEP_DEBUG を true で登録すると、ステップの詳細なログが出力されます。調査が終わったら設定を戻しておきます。
WordPress のコーディング規約チェックを追加する
構文チェックに慣れたら、WordPress のコーディング規約（WordPress Coding Standards）に沿っているかのチェックを足すと、レビューの手間が減ります。PHP_CodeSniffer と WordPress Coding Standards を Composer の開発用依存として入れ、設定ファイル（phpcs.xml.dist など）をリポジトリに置いておく前提で、ステップを1つ追加します。
- name: 依存関係をインストール
run: composer install --no-interaction --no-progress
- name: コーディング規約のチェック
run: vendor/bin/phpcsこの場合は setup-php の tools: none を外すか、tools: composer を指定して Composer を使えるようにします。規約チェックは最初のうち大量の指摘が出ることがあるため、既存のコードでは対象ディレクトリを絞る、警告は失敗扱いにしない、といった段階的な導入が現実的です。
つまずきやすい点
- YAML のインデント: YAML はインデントで構造を表します。タブ文字は使えず、スペースの数がずれると意図しない構造になります。GitHub の画面でファイルを編集すると、構文の誤りがその場で指摘されます。
- ワークフローが動かない: ファイルの置き場所（
.github/workflows/）、拡張子（.ymlまたは.yaml）、onのブランチ名（mainとmasterの違い）を確認します。 - フォークからのプルリクエスト: 外部の人がフォークから送ったプルリクエストでは、セキュリティのためにシークレットが渡されず、
GITHUB_TOKENの権限も制限されます。シークレットを使うステップは、この場合に失敗する前提で設計します。 - 毎回同じ環境ではない:
ubuntu-latestが指す Ubuntu のバージョンは時期によって切り替わります。再現性が重要ならubuntu-24.04のようにバージョンを固定します。 - サードパーティのアクションの信頼性:
usesで呼ぶアクションは他人のコードです。利用者の多い、保守されているものを選び、気になる場合はタグではなくコミットの SHA で固定する方法もあります。
次のステップ
ワークフローの基本が分かれば、応用は組み合わせです。複数の PHP バージョンで同時にテストするならマトリックス（strategy.matrix）、API キーや SSH 鍵を扱うならシークレット、サーバーへの自動反映ならデプロイ用のジョブを追加します。いきなり全部を作ろうとせず、1つのチェックが安定して動くことを確認してから広げていくと、失敗したときに原因を追いやすくなります。
まとめ
- ワークフローは
.github/workflows/に置く YAML ファイルで、on（きっかけ）、jobs（処理のまとまり）、steps（個々の処理）で構成されます。 - 最初の1本は
actions/checkoutでコードを取得し、php -lで構文チェックするところから始めると、仕組みをつかみやすくなります。 permissionsでGITHUB_TOKENの権限を最小限にし、アクションのバージョンは各リポジトリで確認します。- 失敗時は赤いステップのログを読み、必要ならデバッグログで再実行します。
- 規約チェック、マトリックス、シークレット、デプロイと、1つずつ段階的に広げます。