はじめに

個人開発や業務の中でGitHub Actionsを活用するとyamlファイルにワークフローを記述する機会がたびたび生じています。

GitHub Actionsのyamlに記述するフローについて、当初は中々理解しきれなかったのですが、yamlファイルは仮想マシンへの指示書というイメージを掴むことで理解が進んだため気づきを記事にしたいと思います。

公式ドキュメントから見るGitHub Actionsの構造

まずはGitHub Actions公式ドキュメントを見てみます。

GitHub offers hosted virtual machines to run workflows. The virtual machine contains an environment of tools, packages, and settings available for GitHub Actions to use.
訳：GitHubは、ワークフローを実行するためのホスト型仮想マシンを提供しています。この仮想マシンには、GitHub Actionsで使用できるツール、パッケージ、設定などの環境が含まれています。

Runners are the machines that execute jobs in a GitHub Actions workflow. For example, a runner can clone your repository locally, install testing software, and then run commands that evaluate your code.
訳：ランナーは、GitHub Actions ワークフロー内のジョブを実行するマシンです。例えば、ランナーはリポジトリをローカルにクローンし、テストソフトウェアをインストールし、コードを評価するコマンドを実行できます。

ワークフローは、1 つ以上のジョブからなる設定可能な自動化プロセスです。ワークフローの設定を定義するには、YAMLファイルを作成しなければなりません。

上記の公式ドキュメントの要点としては

GitHubにはワークフロー実行用の仮想マシンがある
ワークフローを実行するマシンがランナーと呼ばれる
ワークフローはyamlファイルによって定義される
といったところになります。

つまりyamlファイルは仮想マシン用の指示書と解釈することができるはずです。

ここからyamlファイル内の個別のstepsについて見ていきますが、
ローカル環境で実現できている処理を仮装マシンでも実現させると考えると理解しやすくなるはずです。

yamlファイル内のフローと「仮想マシン」

GitHub Actionsを使う大きな目的としてはローカル環境で実現できている処理を仮想マシン環境でも実現させることなはずです。
(例：ビルド、テスト)

一方で仮装マシンはyamlでの記述があるまではnodeやosが設定されていないため、そのままでは同じ処理を実行することができません。

この両環境の差分を埋めるのがyamlファイル内の記述ということになります。

埋める差分の内容の例

マシンの環境を設定する

初期の仮想マシン内には処理を実行するマシンの種類が設定されていないので、設定することでローカル環境のような実行マシンを準備します。
(ubuntu-latestとなることが多いです)

記述例

runs-on: ubuntu-latest

環境変数を設定する

firebaseなど環境変数の設定が必要な処理については当然仮装マシン上でも環境変数が必要です。

環境変数の設定は下記のドキュメントを参照してください。

記述例

env:
  VITE_FIREBASE_API_KEY: ${{ secrets.FIREBASE_API_KEY }}
  VITE_FIREBASE_AUTH_DOMAIN: ${{ secrets.FIREBASE_AUTH_DOMAIN }}
  VITE_FIREBASE_PROJECT_ID: ${{ secrets.FIREBASE_PROJECT_ID }}
  VITE_FIREBASE_STORAGE_BUCKET: ${{ secrets.FIREBASE_STORAGE_BUCKET }}
  VITE_FIREBASE_MASSAGING_SENDER_ID: ${{ secrets.FIREBASE_MASSAGING_SENDER_ID }}
  VITE_FIREBASE_APP_ID: ${{ secrets.FIREBASE_APP_ID }}

※actions/checkout@v4

多くのワークフローではactions/checkout@v4という処理が必要になります。
こちらに関しては以下の記事が参考になったのでご覧ください。

記述例

steps:
  - name: (任意の名前)
    uses: actions/checkout@v4

node.jsを設定する

仮装マシン上にはnode.jsがインストールされていないため、そのままだとnpm系統のコマンドが処理できません。
なので仮想マシンにnode.jsを導入させます。

ここまで来ればnpm系統のコマンドを処理できるようになるので、インストールやビルドなどの任意のコマンドを実行できるようになります。

記述例

steps:
- name: node installation
    uses: actions/setup-node@v4
    with:
      node-version: 20

最後に

yamlファイルの記載内容は割と詰まることが多いですが、「仮想マシンにローカル環境と同じものを再現する」というイメージで考えるとスムーズに理解できました。
同じように詰まっている人の支えになれば幸いです。