GitHub Pages でのカスタム ワークフローの使用

ワークフロー ファイルを作るか、定義済みのワークフローから選ぶことで、GitHub Actions と GitHub Pages を利用できます。

この機能を使用できるユーザーについて

GitHub Pagesは、パブリック・リポジトリのGitHub Freeと組織用のGitHub Free、パブリック・リポジトリとプライベート・リポジトリのGitHub Pro、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Serverで利用できます。 詳しくは、「GitHub のプラン」をご覧ください。

GitHub Pages で、Jekyll ビルドの実行に GitHub Actions が使用されるようになりました。 ビルドのソースとしてブランチを使用する際、組み込みの Jekyll ワークフローを使用する場合は、リポジトリで GitHub Actions を有効にする必要があります。 GitHub Actions が使用できない場合、または無効になっている場合は、ソース ブランチのルートに .nojekyll ファイルを追加すると、Jekyll ビルド プロセスがバイパスされ、コンテンツが直接デプロイされます。 GitHub Actions の有効化の詳細については、「リポジトリの GitHub Actions の設定を管理する」を参照してください。

この記事の内容

カスタム ワークフローについて

カスタム ワークフローを使うと、GitHub Actions を使って GitHub Pages サイトを構築できます。 その場合でも、使いたいブランチをワークフロー ファイルで選択できますが、カスタム ワークフローを使うとさらに多くのことができます。 カスタム ワークフローを使い始めるには、最初に現在のリポジトリに対してそれを有効にする必要があります。 詳しくは、「GitHub Pages サイトの公開元を設定する」をご覧ください。

configure-pages アクションを構成する

GitHub Actions を使うと、configure-pages アクションを通じて GitHub Pages を使用できます。これにより、Web サイトに関するさまざまなメタデータを収集することもできます。 詳細については、「configure-pages アクション」を参照してください。

アクションを使うには、このスニペットを目的のワークフローの jobs の下に配置します。

- name: Configure GitHub Pages
  uses: actions/configure-pages@v5

このアクションは、任意の静的サイト ジェネレーターから GitHub Pages へのデプロイをサポートするのに役立ちます。 このプロセスの繰り返しを減らすには、最も広く使われているいくつかの静的サイト ジェネレーターでワークフロー テンプレートを使用できます。 詳しくは、「ワークフロー テンプレートの使用」をご覧ください。

upload-pages-artifact アクションを構成する

upload-pages-artifact アクションを使うと、成果物をパッケージ化してアップロードできます。 GitHub Pages 成果物は、1 つの tar ファイルを含む圧縮された gzip アーカイブである必要があります。 tar ファイルのサイズは 10 GB 未満である必要があり、シンボリック リンクやハード リンクを含めることはできません。 詳細については、「upload-pages-artifact アクション」を参照してください。

現在のワークフローでアクションを使うには、このスニペットを jobs の下に配置します。

- name: Upload GitHub Pages artifact
  uses: actions/upload-pages-artifact@v3

GitHub Pages の成果物をデプロイする

deploy-pages アクションは、成果物のデプロイに必要なセットアップを処理します。 適切な機能を確保するには、次の要件を満たす必要があります。

  • ジョブには、少なくとも pages: write と id-token: write のアクセス許可が必要です。
  • needs パラメーターに、ビルド ステップの id を設定する必要があります。 このパラメーターを設定しないと、独立したデプロイが作成されていない成果物を継続的に検索するようになる可能性があります。
  • ブランチとデプロイメントの保護ルールを適用するには、environment を確立する必要があります。 既定の環境は github-pages です。
  • ページの URL を出力として指定するには、url: フィールドを使います。

詳細については、「deploy-pages アクション」を参照してください。

# ...

jobs:
  deploy:
    permissions:
      contents: read
      pages: write
      id-token: write
    runs-on: ubuntu-latest
    needs: jekyll-build
    environment:
      name: github-pages
      url: ${{steps.deployment.outputs.page_url}}
    steps:
      - name: Deploy artifact
        id: deployment
        uses: actions/deploy-pages@v4
# ...

個別のビルド ジョブとデプロイ ジョブをリンクする

build ジョブと deploy ジョブを 1 つのワークフロー ファイルでリンクし、同じ結果を得るために 2 つの個別のファイルを作成する必要がないようにできます。 ワークフロー ファイルの作業を始めるには、jobs でジョブを実行するように build と deploy ジョブを定義できます。

# ...

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Build with Jekyll
        uses: actions/jekyll-build-pages@v1
        with:
          source: ./
          destination: ./_site
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

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

場合によっては、すべてを 1 つのジョブに組み合わせることができます (特に、ビルド プロセスが必要ない場合)。 そうすれば、デプロイ ステップだけに集中できます。

# ...

jobs:
  # Single deploy job no building
  deploy:
    environment:
      name: github-pages
      url: ${{steps.deployment.outputs.page_url}}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # upload entire directory
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

# ...

異なるランナーで、順番に、または並列に実行するように、ジョブを定義できます。 詳しくは、「ワークフロー動作の選択」をご覧ください。