GitHub Actionsの基本まとめ

業務で初めてGitHub Actionsを使って、デプロイ自動化までを行う機会がありましたので、まずは基本からまとめてみようと思いこの記事を書きました。

1. GitHub Actionsとは

GitHub Actionsは、リポジトリにプッシュしたタイミングやプルリクエスト発生時などに自動でジョブを実行できるCI/CDサービスです。以下のような用途でよく使われます。

なぜ必要か？

• 人手による手順の省略・ミス防止
  手動でビルドやテスト、デプロイを行うと手順漏れや設定ミスが発生しやすい。
  GitHub Actions を使って自動化することで、同じ手順を確実に再現でき、ヒューマンエラーを減らせる。

• 開発スピードの向上
  コードをプッシュするたびに自動的にテストやビルドが走るため、問題が早い段階で検知できる。
  問題が起きたタイミングが明確になることで、開発者は問題箇所を素早く特定し、修正に集中できる。

• 品質の担保
  自動テストや静的解析、Lint チェックなどを CI の中で常に実行することで、品質基準を保ったまま開発を進められる。
  テストに合格しないコードはマージできないように設定すれば、本番環境への不具合混入を減らせる。

• デプロイの安定化・迅速化
  CD（継続的デリバリー／継続的デプロイメント）を組み込むと、テスト合格後にステージングや本番環境への反映がほぼワンクリックで完了する。

• チーム開発での透明性向上
  ビルド／テスト結果が GitHub の UI 上でそのまま確認できるため、誰がどのプルリクエストで何が失敗したかをチーム全体で共有できる。ジョブの履歴が残るので、過去にどのコミットでテストが落ちたのかを遡りやすい。

• スケーラブルな運用
  複数のジョブを並列で実行することで、プロジェクト規模が大きくなってもビルド時間をある程度短縮できる。たとえば、異なる OS や Node.js／Python のバージョンでテストを同時に回せるため、多様な環境での動作検証が容易になる。

• 環境の一貫性確保
  ローカル環境で「動いた」「動いていない」が起きるのは、開発者マシンごとに環境構築の差分があるため。GitHub Actions 上のクリーンなランナー環境で毎回同じ手順を行うことで、常に同一条件下でビルド・テストが実行され、環境差による不具合を減らせる。

CI/CD　について

• CI（Continuous Integration：継続的インテグレーション）

  開発者がリポジトリにコードをコミット・プッシュするたびに、自動でビルドやテストを実行し、バグやコンフリクトを早期に検知する仕組み。

  主な目的は「変更を頻繁にマージして、統合時のトラブルを減らす」こと。

  具体的には、プッシュ → 自動ビルド → 自動テスト → 結果フィードバック、という流れになります。

• CD（Continuous Delivery／Continuous Deployment：継続的デリバリー／継続的デプロイメント）

  CI を経た後、さらに「デプロイまで自動化する」段階。

  Continuous Delivery（継続的デリバリー）は、テストを通過したアーティファクトをステージング環境などに自動で配置し、人の判断で本番リリースできる状態にしておく。

  Continuous Deployment（継続的デプロイメント）は、テストに合格したらそのまま自動で本番環境にデプロイまで行う。

• プッシュやPR時のテスト自動実行

• ビルド・デプロイの自動化

• 定期的なメンテナンス作業（スケジュール実行）

• コード解析やLint、フォーマットの自動チェック

2. 基本フォルダ構成

GitHub Actionsのワークフロー定義ファイルは、リポジトリ内の以下のパスに配置します。

.github/workflows/
└── <workflow名>.yml

例えば、ci.ymlというファイル名であれば、.github/workflows/ci.yml のように配置します。
こちら以外の場所に配置しても、動きません。

3. ワークフローの構成要素

ワークフローファイル（YAML）には主に以下の要素を記述します。

• name
  ワークフロー全体の名前。GitHub UI上に表示されます。

• on
  どのイベントをトリガーにしてワークフローを実行するかを指定します。

  • push: ブランチやタグへのプッシュ

  • pull_request: プルリクエストの作成/更新

  • schedule: cron式による定期実行

  • workflow_dispatch: 手動トリガー（GitHub UIから実行）

  • repository_dispatch, issue_comment など、ほか多数

• jobs
  ワークフロー内で実行する「ジョブ（job）」を定義します。
  ジョブごとに動作環境やステップを記述できます。複数ジョブを並列/順序指定して実行できます。

  各ジョブにはruns-onでrunner(実行環境)（Ubuntu・Windows・macOSなど）を指定

  needsを使えば、他のジョブの完了を待ってから実行可能

  ジョブ内に複数のステップ（steps）を定義し、シェルコマンド実行やアクション実行を行う

• steps
  ジョブの中で実行する個々のステップ。

  • uses: 既存のGitHub 公開アクションや自作アクションを呼び出し

  • run: 任意のシェルコマンドを実行

  • with: アクションに引数を渡す

  • env: ステップ単位で環境変数を設定可能

4. 代表的なトリガー例

4.1 push時に特定ブランチで実行

on:
  push:
    branches:
      - main
      - develop

mainとdevelopブランチに対するプッシュを検知してワークフローを実行する。

4.2 プルリクエストの作成・更新時に実行

on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches:
      - main

mainブランチに向けたPRを作成（opened）、更新（synchronize）、再オープン（reopened）されたときに実行。

4.3 スケジュール実行（cron）

on:
  schedule:
    - cron: '0 0 * * *'

毎日0時（UTC）に1回、自動で実行します。cronのタイムゾーンはUTC。

4.4 手動トリガー

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deploy target environment'
        required: true
        default: 'staging'

GitHubのActionsタブから「Run workflow」を押して手動実行できます。上記例ではenvironmentというパラメータを渡せるよう設定しています。

5. 最小構成のワークフロー例

Node.jsプロジェクトのテスト実行を自動化する例です。mainブランチへのプッシュ時に、Ubuntu上でnpm install→npm testを行います。

name: CI

on:
  push:
    branches:
      - main

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    steps:
      - name: リポジトリをチェックアウト
        uses: actions/checkout@v4

      - name: Node.js のセットアップ
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: 依存パッケージをインストール
        run: npm install

      - name: テストを実行
        run: npm test

• actions/checkout@v4：コードをチェックアウト
• actions/setup-node@v4：指定のNode.jsバージョンをインストール
• run：任意のシェルコマンドを実行

6. 複数ジョブ・並列実行

ジョブを複数定義すると、デフォルトでは並列で実行されます。例えば、Linux・Windows・macOSそれぞれでテストを走らせたい場合の例は以下の通りです。

name: Cross-Platform Tests

on:
  push:
    branches:
      - main

jobs:
  test-linux:
    runs-on: ubuntu-latest
    steps:
      - name: コードをチェックアウト
        uses: actions/checkout@v4

      - name: Node.js セットアップ
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: テスト実行 (Linux)
        run: npm test

  test-windows:
    runs-on: windows-latest
    steps:
      - name: コードをチェックアウト
        uses: actions/checkout@v4

      - name: Node.js セットアップ
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: テスト実行 (Windows)
        run: npm test

  test-macos:
    runs-on: macos-latest
    steps:
      - name: コードをチェックアウト
        uses: actions/checkout@v4

      - name: Node.js セットアップ
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: テスト実行 (macOS)
        run: npm test

それぞれのジョブは並列に走り、相互依存がない限り高速に処理されます。

7. ジョブ間の依存関係（needs）

あるジョブの成功を待ってから別のジョブを実行したい場合は、needsを使います。

name: Build and Deploy

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: チェックアウト
        uses: actions/checkout@v4

      - name: ビルド実行
        run: npm run build

      - name: ビルド成果物をアップロード
        uses: actions/upload-artifact@v3
        with:
          name: dist
          path: dist/

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: チェックアウト
        uses: actions/checkout@v4

      - name: アーティファクトをダウンロード
        uses: actions/download-artifact@v3
        with:
          name: dist
          path: ./dist

      - name: デプロイ実行
        run: |
          echo "Deploying to production..."
          # ここにデプロイ処理を記述

8. 環境変数とシークレット

8.1 環境変数（env）

ワークフロー全体、ジョブ単位、ステップ単位で環境変数を定義できます。

jobs:
  example:
    runs-on: ubuntu-latest
    env:
      GLOBAL_VAR: "hello"

    steps:
      - name: ステップ専用環境変数
        env:
          STEP_VAR: "world"
        run: |
          echo "GLOBAL_VAR is $GLOBAL_VAR"
          echo "STEP_VAR is $STEP_VAR"

8.2 シークレット（secrets）

GitHubリポジトリのSettings → Secrets and variables → Actions に登録したシークレットは、secrets.<名前>でアクセスできます。

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: チェックアウト
        uses: actions/checkout@v4

      - name: デプロイ（シークレット利用例）
        run: |
          echo "Secret API_KEY is ${{ secrets.API_KEY }}"

シークレットはワークフロー実行ログには表示されません。

9. よく使う主要アクション例

• actions/checkout：リポジトリのコードをチェックアウトする
• actions/setup-node：Node.jsをインストールする
• actions/setup-python：Pythonをインストールする
• actions/upload-artifact, actions/download-artifact：ビルド成果物のアップロード/ダウンロード
• actions/cache：依存キャッシュを保存し、ビルド高速化を図る
• docker/build-push-action：Dockerイメージのビルド・プッシュ
• peaceiris/actions-gh-pages：静的サイトをGitHub Pagesにデプロイ

例：依存キャッシュを使ってnpm installを高速化する

steps:
  - uses: actions/checkout@v4

  - name: キャッシュを復元
    uses: actions/cache@v3
    with:
      path: ~/.npm
      key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-node-

  - name: Node.js セットアップ
    uses: actions/setup-node@v4
    with:
      node-version: '18'

  - name: 依存をインストール
    run: npm ci

10. まとめ：基本の流れ

1. リポジトリ直下に .github/workflows/ フォルダを作成する
2. <workflow名>.yml ファイルを配置する
3. name、on、jobs の構成を記述する
4. 必要なアクション（checkout, setup-node など）やシェルコマンドを steps に記述する
5. シークレットや環境変数は secrets.<名前>／env で管理する
6. プッシュやPR発生時など、設定したトリガーで自動実行される

これらがGitHub Actionsの基本的な構文と仕組みですね。まずは簡単なテスト系ワークフローを作成し、GitHub上で成功したか確認しながら少しずつ機能を追加してくというのが良いかなと思います。

---

株式会社シンシアでは、実務未経験のエンジニアの方や学生エンジニアインターンを採用し一緒に働いています。
※ シンシアにおける働き方の様子はこちら
https://www.wantedly.com/companies/xincere-inc/stories
弊社には年間100人程度の実務未経験の方に応募いただき、技術面接を実施しております。
この記事が少しでも学びになったという方は、ぜひ wantedly のストーリーもご覧いただけるととても嬉しいです！