📄

GitHub PagesにアップロードするGitHub Actions

2023/01/06に公開

GitHub Actions

参考文献

最小構成

あらかじめ、リポジトリの Settings > Pages から、Sourceを GitHub Actions に変更しておいてください。

ワークフローを記述します。

name: CI

on:
  push:
    branches: [ "main" ]
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: |
          mkdir data
          echo "<h1>Hello GitHub Pages!</h1>" > data/index.html          
      - uses: actions/upload-artifact@v3
        with:
          name: my_site
          path: data
      - uses: actions/upload-pages-artifact@v1
        with:
          path: data
          
  deploy:
    needs: build
    runs-on: ubuntu-latest 
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    permissions:
      pages: write
      id-token: write
    steps:
      - uses: actions/deploy-pages@v1
        id: deployment

実行が終わると、当該Actionのサマリ画面や、先ほど変更したSettingsページ等にPagesのURLが示されます。

出来上がりの例はこちら。

実例1. Python - FastAPI

あとは、上の例でechoにより即席HTMLを作っていた箇所を、お好みに変えるだけです。用例としてはAPIドキュメントの生成・公開というのが良くあるのではないかと思います。

FastAPIのReDocドキュメントを公開する例を示します。

FastAPIはOpenAPIのSpecificationファイル(JSON)を簡単に出力できます。openapi()メソッドを呼ぶだけです。

main.py

from fastapi import FastAPI
app = FastAPI()

# (エンドポイント定義)

def print_spec() -> None:
    print(app.openapi())

以下は、OpenAPI SpecをJSONファイルで出力し、さらにredoc-cliでHTMLにする例です。Spec JSONを得るところ(Pythonの実行方法)は、Poetryを使っているなど状況により変わると思いますので、適宜読み替えてください。

fastapi.yaml

name: FastAPI

on:
  push:
    branches: [ "main" ]
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 5

    steps:
      # (予めPython, Poetry等の環境構築をする。省略。)
    
      - name: Build OpenAPI spec
        run: |
          python -c "from main import print_spec; print_spec()" > openapi_spec.json

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "18"

      - name: Build ReDoc HTML
        run: |
          npm install -g redoc-cli
          redoc-cli bundle openapi_spec.json
	  mkdir pages
          mv redoc-static.html pages/my_doc.html
	  
      # 以降は同じ
      - uses: actions/upload-artifact@v3
        with:
          name: fastapi_doc
          path: pages
      - uses: actions/upload-pages-artifact@v1
        with:
          path: pages

  deploy:
    needs: build
    runs-on: ubuntu-latest 
    timeout-minutes: 5
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    permissions:
      pages: write
      id-token: write
    steps:
      - uses: actions/deploy-pages@v1
        id: deployment

実例2. C# - DocFX

C#でのAPIドキュメント生成の例です。以下の記事では古い方法でGitHub Pagesにアップロードしており^[1]、少し変えるだけです。

dotnet.yaml

name: DocFX

on:
  push:
    branches: [ "main" ]
  workflow_dispatch:

jobs:
  build:
    runs-on: windows-latest
    
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: DocFX
        shell: cmd
        run: |
          choco install docfx -y
          docfx docfx\docfx.json

      # 以降は同じ
      - uses: actions/upload-artifact@v3
        with:
          name: dotnet_doc
          path: docfx/_site
      - uses: actions/upload-pages-artifact@v1
        with:
          path: docfx/_site

  deploy:
    needs: build
    runs-on: ubuntu-latest 
    timeout-minutes: 5
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    permissions:
      pages: write
      id-token: write
    steps:
      - uses: actions/deploy-pages@v1
        id: deployment

ほかにも、コードカバレッジの詳細結果HTMLをアップロードするのも価値がありそうです。

脚注

執筆当時はまだ本記事の新しい方法はありませんでした。 ↩︎

参考文献

最小構成

実例1. Python - FastAPI

実例2. C# - DocFX

Discussion