Docusaurusで作ったサイトがドキュメントの変更がコミットされるたびに自動更新されるようGitHub Actionsを設定する

11220 ワード
Docusaurus GitHubActions ドキュメント ドキュメント テキストリンク

はじめに

本記事は、DocusaurusのGitHub Actionsを設定してGitHubでドキュメントが変更されたらサイトが自動更新されるよう設定するためにやったことをまとめた記事です。公式ドキュメントはこちら。
Docusaurusについて知りたい方、DocusaurusのGitHub Pagesへのデプロイ方法はこちらをご覧ください。

SSHキーの作成

まず初めにSSHキーというものを発行します。GitHub公式サイトでの発行手順と若干異なります。こちらを参考にしました。
SSHキーを格納するフォルダへ移動します。GitHub公式サイトでの発行手順通りにやると、デフォルトでは、C:\Users\{ユーザー名}\.sshに作成されるので、ここでいいかと思います。

cd C:\Users\{ユーザー名}\.ssh`

以下を実行してSSHキーを発行します。
参考サイトによると、個人に紐づいたSSHキーの使用はセキュリティ上よくないとのことでした。以下のコマンドによって作成するGitHubActionsで使用するための専用のSSHキーの使用が推奨されていました。
{ }部分は任意のファイル名に置き換えてください。特に拡張子の指定は必要ありません。

ssh-keygen -t ed25519 -a 100 -f {SSHキーを格納するファイルのファイル名}

例えば、以下のようなコマンドを実行します。

ssh-keygen -t ed25519 -a 100 -f id_ed25519_docusaurus

また、このコマンドの実行後、パスフレーズの入力が求められますが、エンターキーを押してすべて無視してください。
GitHub ActionsでSSHキーを使う場合は、パスフレーズの無いSSHキーでないと使用できないようです。（詳しくはこちら）

次に、以下のコマンドでデプロイキー(公開鍵)をクリップボードにコピーしておきます。id_ed25519_docusaurusの部分は任意のファイル名に置き換えてください。

clip < id_ed25519_docusaurus.pub

GitHub Actionsへの設定

クリップボードにコピーしたキーをDocusaurusをデプロイしたリポジトリに設定します。
リポジトリのSetteingsのDeploy KeysのAdd New Deploy Keyをクリックします。
Titleには任意の文字列を設定し、Key欄に先ほどクリップボードにコピーしたキーを貼り付けます。
Allow write accessにチェックを付けて、Add keyをクリックします。

次に、秘密鍵を設定します。
GitHubのリポジトリのページの、SettingsのSecretsのNew Repository Secretsをクリックします。

NameにはGH_PAGES_DEPLOYと入力します。
以下のコマンドで秘密鍵をコピーして、Value欄に貼り付けます。id_ed25519_docusaurusの部分は任意のファイル名に置き換えてください。
その後、Add secretをクリックします。

clip < id_ed25519_docusaurus

次に、リポジトリの/.github/workflows/フォルダにymlファイルを格納します。今回は、docusaurus.ymlとしました。
ymlファイルの中には以下のように記載します。前提として、mainブランチのdocs/website/フォルダ以下のファイルが変更された場合にのみこのアクションが実行されるように設定しています。

name: Docusaurus

on:
  workflow_dispatch:
  push:
    branches: [main]
    paths: [ 'docs/website/**' ]
  pull_request:
    branches: [main]
    paths: [ 'docs/website/**' ]

env:
  # websiteのあるフォルダ
  SOURCE_FOLDER: docs/website

jobs:
  checks:
    if: github.event_name != 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: '14.x'
      - name: Test Build
        run: |
          if [ -e yarn.lock ]; then
            yarn install --frozen-lockfile
          elif [ -e package-lock.json ]; then
            npm ci
          else
            npm i
          fi
          npm run build
        working-directory: ${{env.SOURCE_FOLDER}}
  gh-release:
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: '14.x'
      - uses: webfactory/[email protected]
        with:
          ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}
      - name: Release to GitHub Pages
        env:
          USE_SSH: true
          GIT_USER: git
        run: |
          git config --global user.email "xxx@yyy"
          git config --global user.name "zzz"
          if [ -e yarn.lock ]; then
            yarn install --frozen-lockfile
          elif [ -e package-lock.json ]; then
            npm ci
          else
            npm i
          fi
          npm run deploy
        working-directory: ${{env.SOURCE_FOLDER}}

上記ymlファイルにおいて以下の部分は置き換えが必要です。

PathsおよびSOURCE_FOLDERはDocusaurusをインストールした任意のフォルダに置き換えてください。
また、branchesも必要があれば任意のブランチに置き換えてください。

on:
  workflow_dispatch:
  push:
    branches: [main]
    paths: [ 'docs/website/**' ]
  pull_request:
    branches: [main]
    paths: [ 'docs/website/**' ]

env:
  # websiteのあるフォルダ
  SOURCE_FOLDER: docs/website

user.emailおよびuser.nameはご自身がGitHubに登録しているメールアドレスおよびユーザー名に書き換えてください。

        run: |
          git config --global user.email "xxx@yyy"
          git config --global user.name "zzz"

これで、メインブランチのdocs/website/以下に変更があるたびに、このアクションが走り、Docusaurusで作成したサイトが更新されるようになります。

ちなみに、手動でテスト可能なようにymlファイルを作りましたので、以下のようにテスト可能です。
ymlファイルがリポジトリに追加されると、Actionsタブに追加したymlファイルのnameが左側のworkflows以下に表示されると思うので、それをクリックします。
すると、右の方にRun workflowというドロップダウンが表示されますので、それをクリックします。
すると、Run workflowという緑色のボタンが出てきますので、それをクリックすることで、手動実行できます。

以上で、Github Actions の設定は完了です。

さいごに

Docusaurusの公式ドキュメントには、パスフレーズの無いSSHキーを作成するとは書いていなくて、そこでつまりました。
GitHub Actionsの方のドキュメントには書いてあるので、間違ってはないと思います。お役に立てれば幸いです。
最後までお読みいただきありがとうございました。