本記事では、GitHub Actionsの基本的な扱い方は知っているものとして進めています。GitHub Actionsの基本的な事項は他の記事などをご参照ください。

要約

ルートディレクトリ直下の/frontendフォルダにソースがあるとして、以下のようなワークフローを設定しました。mainブランチにpushされた場合（マージされた場合）にデプロイが実行されます。

参考として、以下のリポジトリのサイトはこの記事の方法でデプロイしています。

ソースコード全文

deploy.yaml

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4.1.6

      - name: Install Node.js
        uses: actions/setup-node@v4.0.2
        with:
          node-version: 20

      - name: Install pnpm
        uses: pnpm/action-setup@v4
        with:
          package_json_file: frontend/package.json

      - name: Install packages
        working-directory: frontend
        run: pnpm install

      - name: Build
        working-directory: frontend
        run: pnpm run build

      - name: Upload Pages Artifact
        uses: actions/upload-pages-artifact@v3.0.1
        with:
          path: "frontend/dist/"

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4.0.5

/frontend/package.json

{
  "name": "hoge",
  "type": "module",
  "version": "0.0.1",
  "packageManager": "pnpm@9.1.4+sha512.9df9cf27c91715646c7d675d1c9c8e41f6fce88246f1318c1aa6a1ed1aeb3c4f032fcdf4ba63cc69c4fe6d634279176b5358727d8f2cc1e65b65f43ce2f8bfb0",
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro check && astro build",
    "preview": "astro preview",
    "astro": "astro"
  },
  "dependencies": {
    "@astrojs/check": "^0.6.0",
    "astro": "^4.8.2",
    "typescript": "^5.4.5"
  },
  "devDependencies": {
    // （省略） //
  }
}

背景

Astroで作成したWebページを、GitHub Pagesでホスティングするために、GitHub Actionsのワークフローを作成しました。

以下のドキュメントに、公式の用意したActionsの説明がありましたが、pnpmの使用＋サブディレクトリにソースがあるという少し特殊な環境ゆえか当時実装しようとしていた時にはうまく動作しませんでした。（※こちらのPRで既に修正されているかもしれません）

そこで、node.js＋pnpmを使ってビルドしGitHub Pagesにデプロイする自前のワークフローを設定したので、それをこの記事にまとめます。

実装

ワークフローの流れは以下のようになっています。前半はNode.jsを使用したシンプルなビルドの手順となっていて、後半は公式のドキュメントにも書かれている手順に準拠したものになっています。

Actionsのチェックアウト
Node.jsのセットアップ
pnpmのセットアップ
pnpmによる依存パッケージのダウンロード
pnpm run buildによるビルド
GitHub Pagesへのアップロード

`deploy.yaml`

ワークフローは以下のように定義しました。プロジェクトのソースは/frontendフォルダにあるものとしています。mainブランチにPRがマージされた際などにこの処理が実行されます。

deploy.yaml

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4.1.6

      - name: Install Node.js
        uses: actions/setup-node@v4.0.2
        with:
          node-version: 20

      - name: Install pnpm
        uses: pnpm/action-setup@v4
        with:
          package_json_file: frontend/package.json

      - name: Install packages
        working-directory: frontend
        run: pnpm install

      - name: Build
        working-directory: frontend
        run: pnpm run build

      - name: Upload Pages Artifact
        uses: actions/upload-pages-artifact@v3.0.1
        with:
          path: "frontend/dist/"

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4.0.5

処理を順を追って説明します。

まずactions/setup-node@v4.0.2でNode.jsのインストールを、pnpm/action-setup@v4でpnpmのインストールをしています。

pnpmのインストールのActionでは、pnpmのバージョンを指定する必要があります。私の場合は後述のpackage.json内に"packageManager"のプロパティでバージョンを指定しています。それがない人は deploy.yaml内にversion: 9のような指定が必要になります。詳細は以下をご確認ください。

続いて/frontendディレクトリで実行することを working-directory: frontend の記述で指定し、pnpm installおよびpnpm buildを実行しています。これによりデフォルトの設定では /frontend/dist/以下にAstro.jsのビルド結果が出力されます。

ビルド結果が生成されたら、それをactions/upload-pages-artifactのActionを使って、アップロードします。公式の説明に従って path: "frontend/dist/"で静的ファイルのパスを指定しています。

「どこにアップロードするの？」というのが気になって調べてみましたが、ジョブの途中のデータをGitHub公式の提供するArtifactというデータ領域にアップロードし永続化しているようでした。actions/upload-pages-artifactのソースコードを見ると、actions/upload-artifactという別のActionを実行してアップロードしています。（参考）

最後は、先ほどArtifactにアップロードした静的ファイルを実際にGitHub Pagesとしてデプロイします。これも公式の提供しているactions/deploy-pagesのワークフローを、ドキュメントのまま実行しています。ドキュメント曰く、アップロード時のArtifactの名前をartifact_name: "hoge"のように任意に指定することもできるようです。

`package.json`

プロジェクトのpackage.jsonの中身についてもこちらに載せています。

特筆すべきなのは、Actions中の pnpm run buildで実行されるスクリプトと、packageManagerのプロパティでしょうか。pnpm run buildで実行されるスクリプトについてはデフォルトのもので、"build": "astro check && astro build"を設定しています。

packageManagerのプロパティは、使用するpnpmのバージョンを指定しています。これは私がcorepackという機能を使用しているために追加されているものです。もしpackageManagerのプロパティがない場合には、先述の通りActions中のpnpm/action-setupの時に使用するpnpmのバージョンを明示しなくてはいけないのでご注意ください。

/frontend/package.json

{
  "name": "hoge",
  "type": "module",
  "version": "0.0.1",
  "packageManager": "pnpm@9.1.4+sha512.9df9cf27c91715646c7d675d1c9c8e41f6fce88246f1318c1aa6a1ed1aeb3c4f032fcdf4ba63cc69c4fe6d634279176b5358727d8f2cc1e65b65f43ce2f8bfb0",
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro check && astro build",
    "preview": "astro preview",
    "astro": "astro"
  },
  "dependencies": {
    "@astrojs/check": "^0.6.0",
    "astro": "^4.8.2",
    "typescript": "^5.4.5"
  },
  "devDependencies": {
    // （省略） //
  }
}

備考

Node.jsのインストールや依存パッケージのインストールについて、結果をキャッシュしておくことでデプロイにかかる時間が短縮できるのかなと思います。私自身がまだActionsのキャッシュについてあまり理解できていないので、この記事では省いております。興味のある方は、ぜひ他の記事などを参考にしてください。

参考