Contents
GitHub Actions ワークフロー作成方法【2023年最新版】
GitHub Actionsのワークフローを作成することで、コードのビルド・テスト・デプロイを自動化できます。本記事では具体的な手順と実装例をステップバイステップで解説し、読者自身がリポジトリで実践できるよう指導します。
GitHub Actionsとは？なぜワークフローを作成するか
GitHub Actionsは、コードの変更をもとに自動的にタスクを実行するCI/CDプラットフォームです。
ワークフローの作成は、継続的インテグレーション（CI）やデプロイの効率化に不可欠で、以下のようなシーンで活用されます。
- マージ前の自動テスト実行
- リリース時のバージョン番号更新
- コード品質のチェック（ESLintなど）
workflow.ymlファイルの基本構造と書き方
ワークフローは.github/workflows/ディレクトリに配置されるYAMLファイルで定義されます。
以下が主要なフィールドとその役割です。
| 項目 | 説明 | 例 |
|---|---|---|
name |
ワークフローの表示名 | TypeScript CI |
on |
イベントトリガー（後述） | push, pull_request |
jobs |
実行するジョブの定義 | build, test, deploy |
YAMLファイルの作成手順
- リポジトリに
.github/workflows/ディレクトリを作成 - 新しいYAMLファイル（例:
typescript-ci.yml）を作成 - 基本構文を以下の通り記述
|
1 2 3 4 5 6 7 8 9 10 11 |
name: TypeScript CI on: push: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - name: Check out code uses: actions/checkout@v3 |
注意点：YAMLはインデント（スペース）が構文の一部なので、エラーを避けるためにツールで検証することをおすすめします。
イベントトリガーの設定方法
ワークフローの実行タイミングはonキーワードで定義します。以下が代表的なイベントです。
基本イベントと用途
push: ブランチへの変更時（例: mainブランチへのプッシュ）pull_request: プルリクエスト作成時schedule: 時間指定で実行（例: 週1回のバージョンチェック）
条件分岐による精度制御
branchesやpathsを使って特定のブランチ/ファイル変更に反応させます。
|
1 2 3 4 5 6 7 |
on: push: branches: [develop] paths: - 'src/**' - '!docs/**' # ドキュメント変更は除外 |
ジョブとステップの定義方法
1つのワークフローで複数ジョブを実行でき、並列/順次処理が可能です。
複数ジョブの並列・順次実行
- 並列: 各ジョブを独立して実行（
jobs配下に別々に記述） - 順次:
needsキーワードで依存関係を指定
|
1 2 3 4 5 6 7 |
jobs: build: needs: [checkout] steps: ... test: needs: build |
ステップ単位でのタスク分解
1つのジョブは複数のステップに分割できます。usesで公式アクション、runでカスタムコマンドを指定。
|
1 2 3 4 |
steps: - name: Install dependencies run: npm install |
GitHub Actionsアクションの活用方法
アクションは「タスクの再利用可能なコード」です。GitHub Marketplaceから導入可能です。
公式アクションの検索・導入手順
- GitHub Marketplaceにアクセス
- 検索バーで「checkout」「setup-node」などキーワードを入力
- 依存関係として
uses: <owner>/<action>@<version>の形式で記述
|
1 2 3 |
- name: Setup Node.js uses: actions/setup-node@v3 |
カスタムアクションの作成・配布
- 自分のリポジトリにアクションを保存（例:
actions/my-action） .github/actions/ディレクトリに配置- 他のリポジトリで
uses: ./my-action@latestと参照可能
注意: GitHub Actionsの標準構造では、カスタムアクションは
.github/actions/に配置するのが推奨されています。
ワークフローのテストとデバッグ手法
作成後の検証は以下の手順で行います。
手動実行による検証
- GitHubリポジトリの「Actions」タブを開く
- 対象ワークフローを選択し、「Run workflow」をクリック
- 実行結果のログを確認
ログ分析とエラーメッセージの読み方
- 失敗時のログは
Error:やfatal:で始まる runコマンドの出力が見たい場合はset -eを追加
よくあるトラブルシューティングチェックリスト
- ファイルの保存場所（
.github/workflows/内か？） - イベントトリガーの設定（
on:の条件が正しいか？） - アクションバージョンの指定（
@latestと@v3などの明示）
実践！あなたのリポジトリでワークフローを作成しよう
ここまでの知識を活用し、読者のリポジトリにワークフローを実装してください。
作成後のベストプラクティス
- バージョン管理: アクションのバージョンを固定（
@v3など） - コメント追加:
# 実行環境: Ubuntuなどの説明を記述 - 継続的インテグレーション（CI）との連携例
- GitHub Pagesに自動デプロイ
- Slackへビルド結果通知
エラーハンドリングの具体例
|
1 2 3 4 5 6 |
steps: - name: Check out code uses: actions/checkout@v3 with: fetch-depth: 0 # 全てのコミットを取得 |
まとめ
- ワークフローは
.github/workflows/ディレクトリに配置されたYAMLファイルで定義される onキーワードでイベントトリガー、jobsでタスクを並列・順次実行可能- GitHub Marketplaceからアクションを検索し、カスタムアクションも作成できる
- テストは「Actions」タブで手動実行し、エラーメッセージで原因特定
これらのステップに従えば、自身のリポジトリでもすぐにワークフローを作成できます。本記事を参考に、ぜひ実践してください。