初心者向け！GitHub Actions をはじめる

はじめに

プロジェクトにGitHub Actionsが設定されているけれど、何を実行しているのかよくわからない…という人は多いかもしれません。
今回、新規プロジェクトでゼロからGitHub Actionsを構築したので、その経験をもとにまとめました。

• GitHub Actionsで何ができるのか知りたい方
• 構築の仕方がわからない方
• GitHub Actionsをなんとなく知っているけど中身はよくわからない方

など初心者でも理解できる内容を目指しています！
また、GitHub Actionsをローカルで実行する方法についても解説しているのでぜひ参考にしてください！

GitHub Actions とは

GitHub Actions は、ビルド、テスト、デプロイのパイプラインを自動化できる継続的インテグレーションと継続的デリバリー (CI/CD) のプラットフォームです。

https://github.co.jp/features/actions
要するに手動での作業を GitHub 上で自動化できるサービスです。

GitHub Actions でどんなことが自動化できるのか

GitHub Actions を活用すると、開発フローのさまざまなプロセスを自動化できます。具体的には以下のようなことが可能です。

• プルリクエスト作成時に、自動でユニットテストや統合テストを実行
• プルリクエスト作成時に、特定のユーザーを担当者として割り当てる
• プッシュ時に、アプリケーションをビルドし、エラーがないか確認
• プッシュ時に、ESLintやPrettierを実行して、コードスタイルを確認
• マージ時に、自動でアプリケーションをサーバーにデプロイ
• ワークフローが失敗した場合、Slackやメールで通知

上記は一例で、このように実行条件と実行内容を指定して幅広いプロセスを自動化することができます。

ワークフローの作り方

ワークフローとは上記例で示したような一連の自動化プロセスのことを指します。
以下の手順で作成します。

1. フォルダを作成
   リポジトリのルートディレクトリに以下のフォルダ構造を作成します。
   .github/workflows/

.github/workflows/の名前が間違っていると動作しません。

2. YAMLファイルを作成
   1で作成したフォルダ内に、ワークフローを定義したYAMLファイルを作成します。ファイル名に指定はありません。
   .github/workflows/workflow-name.yml

3. YAMLファイルに内容を記述
   ワークフローの動作条件や実行内容をYAML形式で記述します。

YAMLファイルの中身

ワークフローはYAMLファイルに定義します。完成した状態のYAMLファイルはこんなイメージです。

name: PR Check

on:
  pull_request: # プルリクエスト作成時に実行

jobs:
  build: # 1つ目のジョブ
    name: Run Build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Run build
        run: echo "Running build..." # 実際には必要なスクリプトやコマンドを記述

  test: # 2つ目のジョブ
    name: Run Tests
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Run tests
        run: echo "Running tests..." # 実際には必要なスクリプトやコマンドを記述

  lint: # 3つ目のジョブ
    name: Run Linter
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Run lint
        run: echo "Running linter..." # 実際には必要なスクリプトやコマンドを記述

一つずつ分解して説明していきます。

name ワークフローの名前を定義

ワークフローの名前を定義します。
GitHubの「Actions」タブに表示されます。

name: PR Check

on 実行タイミングを定義

ワークフローを実行するタイミング（トリガー）を指定します。

on:
  pull_request: # プルリクエスト作成時に実行

指定値	タイミング
push	コードがリポジトリにプッシュされたとき
pull_request	プルリクエストが作成、更新、またはマージされたとき
deployment	デプロイ時
release	リリース時
issues	GitHub Issues関連の処理発生時
schedule	cronによる定期実行

トリガーはめちゃくちゃたくさんあります。
https://docs.github.com/ja/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#about-events-that-trigger-workflows

jobs 実行内容を定義

GitHub Actionsで実行するタスクです。
jobsの中には複数のジョブを定義することができます。

jobs:
  build: # 1つ目のジョブ
    name: Run Build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Run build
        run: echo "Running build..."

  test: # 2つ目のジョブ
    name: Run Tests
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Run tests
        run: echo "Running tests..."

  lint: # 3つ目のジョブ
    name: Run Linter
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Run lint
        run: echo "Running linter..."

複数ジョブのGitHub上の表示です。nameに設定したジョブ名が表示されます。

1つのジョブの中には実行環境（ランナー）とさらに具体的な作業（ステップ）を記載します。

runs-on

ジョブを実行するための実行環境（ランナー）を指定します。

    runs-on: ubuntu-latest # 実行環境（ランナー）

指定値	実行環境
ubuntu-latest	最新のUbuntu
windows-latest	最新のWindows
macos-latest	最新のmacOS

次項で説明するstepsではrun-onの部分で指定したOSのコマンドを使用することができます。
たとえばubuntu-latestを指定した場合、UNIX系のコマンドが使用できます。

steps

ステップはジョブの中で実行される最小単位の作業です。ステップの中にはrunとusesがあります。

    steps: # 具体的な作業（ステップ）
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Run tests
        run: echo "Running tests..." # テストコマンドをここに記載

① run

runは任意のコマンドやスクリプトを実行します。

        run: echo "Running linter..." 

今回は例としてメッセージの出力をしているだけですが、実際にはプロジェクトに応じたスクリプトやコマンドを記述します。npm run testなど。

② uses

usesは GitHub Actions 内で再利用可能なアクション（他の開発者やGitHubが作成したコード）を指定して利用することができます。
runを自分で細かく指定してもいいですが、よく使われる実行内容は他の開発者があらかじめ用意しており、それを使用することができます。

        uses: actions/checkout@v4 # リポジトリの取得

たとえば以下のようなアクションはすでに用意されており、利用することができます。

• リポジトリの取得
• Node.js環境のセットアップ
• Dockerイメージのビルドとプッシュ

他にもたくさんアクションが用意されています。
https://github.com/marketplace?type=actions

GitHub Actions をローカルで実行する

続いて、作成したワークフローが正しく動くか検証します。
ワークフローの確認はGitHub上で確認できますが、新しいワークフローを作成、更新したときや、資材の実装を追加したとき、毎回pushしてワークフローが通るかを確認し、落ちたら修正してを繰り返すのは手間がかかります。また、余計なコミットを残したくありません。
そんなとき、act を利用することでワークフローをローカルで実行して確認することができます。

https://github.com/nektos/act

act をインストールしてローカルで実行する

actをインストールします。

$ brew install act

実行します。

$ act

Apple Mシリーズの互換性問題の警告

Apple Mシリーズのチップ（M1, M2など）を使用している場合、互換性の問題が発生する警告が出てきます。

INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' 
WARN  ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠  

その場合--container-architecture linux/amd64をつけて実行します。

$ act --container-architecture linux/amd64 

一部のワークフローのみを流す

流すことができるワークフローのリストを表示できます。

$ act -l

-W オプションを使用して、対象のワークフローのファイルパスを指定することができます。

例：pr-check.ymlファイルのワークフローを実行

act -W .github/workflows/pr-check.yml

ワークフロー内のさらに一部のジョブのみを流す

-j オプションを使用して、ワークフローの中に複数定義されたジョブの中で一部のジョブのみを流すことができます。

例：pr-check.ymlファイルのワークフローのなかのbuildジョブのみを実行

act -W .github/workflows/pr-check.yml -j build

こんな感じでログが出る

こんな感じでログが出ます。
🏁 Job succeeded

まとめ

GitHub Actions を活用すると、開発フローのさまざまなプロセスを自動化できます。
仕組みや設定内容を理解することで、ワークフローを自分で作成できるだけでなく、ワークフロー実行時のエラーが発生した際にも原因を特定し、解決できるようになります。
まずはぜひ、自分のプロジェクトでGitHub Actionsがどのように設定されているか確認してみてください！