はじめに
本記事は、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/ssh-agent@v0.5.0
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の方のドキュメントには書いてあるので、間違ってはないと思います。お役に立てれば幸いです。
最後までお読みいただきありがとうございました。