Astroの光線のサムネイル。

pubDate: 2024-06-22

author: sakakibara

astro

公開学習

後退

コミュニティ

GitHub Pagesとは

github pagesとはGitHubが提供する(静的)サイトホスティングサービスである。 リポジトリにhtmlファイルを置くことで、https://username.github.io/repo-name/file_name.htmlのようにそのページへアクセスできるようになる。

最高では？と思うかもしれないが、使用にあたりいくつかの制限がある。

どれも”そりゃそうだ”と思う制限ではあるが、正直”既存のWebサイトのコピーを…”の部分はテストサイトをデプロイする際に踏んでしまいがちな地雷かもしれない。

Jekyllを使うことによってmarkdownファイルによるデプロイやカスタムドメインの設定などができる。 また、GitHub Actionsを使って自動デプロイすることも可能であり、かなり多くのニーズを取り込んでいるサービスである。

最も簡単な使い方

多くの場面でちょっとした静的サイトデプロイの候補として挙げられるGitHub Pagesだ。 その手軽さが売りであり、最も多くの使用方法はリポジトリのルートにindex.htmlをおくことだろう。

左上のsettingsから 右サイドバーのナビゲーションバーからPagesを選択し、Build and deploymentのDeply from a branchを選択する。ここで好きなブランチを選択し、好きなブランチを選択する。 つぎに、ディレクトリを選択する。 /を選択するとリポジトリのルートにindex.htmlがある場合、/docsを選択すると/docs/index.htmlがある場合にデプロイされる。 custom domainも設定することができる。

これでhttps://username.github.io/repo-nameでアクセスできるようになる。

あまりにも簡単すぎて説明することがないが、これがGitHub Pagesの基本的な使い方である。

GitHub Actionsを使った自動デプロイ

リポジトリのルートや/docsにindex.htmlを作成しなければならないのだろうか？

それは嫌なのでgithub Actionsを(少々)カスタマイズしてデプロイする手法について説明しよう。

静的サイトのデプロイ

ローカルリポジトリで.github/workflowsディレクトリを作成しその中に適当なyamlファイルを作成する。

working directoryにindex.htmlがあるような場合(今までのような場合)では以下のようにyamlファイルを記述し、git pushすれば自動でデプロイされる。

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages


on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]


  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:


# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write


# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false


jobs:
  # Single deploy job since we're just deploying
  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 repository
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

ここでつまづきやすいのはon>push>branchesであり、 settings>Environments>github-pages>Deployment branches and tagsでmainを指定していなければdeployされない。 好きなブランチを指定しよう。 また

uses: actions/upload-pages-artifact@v3
with:
  # Upload entire repository
  path: '.'

のpathを指定することでデプロイするディレクトリを指定できる。 例えば、dist/index.htmlに公開したいファイルが置かれているなら

uses: actions/upload-pages-artifact@v3
with:
  # Upload entire repository
  path: './dist'

のようにすれば良い。

ビルド & デプロイ

index.htmlをpushと同時にbuildして特定のファイルに生成されたファイルをデプロイするにはどうしたらいいだろうか。

先ほどのyamlファイルのように多少の変更を加えるだけでビルド & デプロイが可能になる。

例えば次のようなディレクトリがあるとする。

Terminal window
❯ ls
dist  LICENSE  node_modules  package.json  package-lock.json  README.md  scripts  src

ここで

Terminal window
npm run build

のようなコマンドでdistディレクトリにindex.htmlが生成されるとする。

そのような場合、.github/workflows/deply.yamlを次のように記述する。

name: Deploy Resume with GitHub Pages dependencies preinstalled


on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]


  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:


# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write


# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false


jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Build with npm
        run: |
          npm install
          npm run build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: "./dist"


  # 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

注目すべきはここである。

- name: Build with npm
run: |
  npm install
  npm run build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
  path: "./dist"

runの中でビルドコマンドを実行し, pathでビルドされたファイルが置かれているディレクトリを指定する。 これでgit pushするだけでビルド & デプロイが可能になる。

これでhttps://username.github.io/repo-name/distではなく https://username.github.io/repo-name/のようにアクセスできるようになる。

最高だね！

ちょっと詳しく

github pagesをGitHub Actionsでデプロイする際に重要なactionが3つある。

それぞれがGitHub Pagesのデプロイに必要な機能を提供している。 それぞれ、

といった機能を提供している。

だが、ほとんどの場合、どのようなartifactsをデプロイするかが開発者にとって重要である。 そこでactions/upload-pages-artifactを使ってデプロイするファイルを指定することができる。その使用方法は各リポジトリのaction.ymlに記載されている。