GitHub Actionsを用いてGitHub Pagesへのデプロイを自動化する

日時

2020/01/18

作者

辻大志郎

概要

GitHub Actions を用いて HTML ファイルの生成とデプロイを自動化します。ドキュメントのホスティング方法はいくつかありますが、ここでは GitHub Pages を用います。masterブランチの/docsに公開するファイルを格納し、公開するようにします。gh-pagesブランチにデプロイして公開する方法もありますが、今回は割愛します。

GitHub Pages を使ったホスティング方法はGithub Pagesを使ってドキュメントを公開もご覧ください。

リポジトリのディレクトリ構成

下記のディレクトリ構成を想定します。

.
├── .github/workflows/main.yml   // GitHub Actions の設定
├── Makefile
├── README.rst
├── docs                         // sphinx-build で生成するファイルの格納先
├── make.bat
├── requirements.txt
└── source                       // rst ファイルの格納先

Makefileは以下のようにdocs以下にビルドファイルを生成するようにします。

注釈

GitHub Pages でホスティングする場合はdocsディレクトリに.nojekyllを含めておく必要があります。.nojekyll自体は空のファイルで OK です。

GitHub Pages の設定

GitHub Actionsで自動生成したファイルをコミットするためにプロジェクトのDeploy keysを設定します。

警告

GITHUB_TOKENPersonal access tokensを用いる場合でもコミットすることはできますが、ページがデプロイされないという問題があります。こちらの GitHub の Community Forum でも同じような議論があり、現在(2020/01/18)は解決はされていません。そのためDeploy keysを使ってコミットします。

Deploy keys の設定

以下のようにして公開鍵と秘密鍵のペアを生成します。

ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f my-repo -N ""

そうすると以下の 2 つのファイルが生成されます。

  • my-repo.pub (公開鍵)

  • my-repo (秘密鍵)

公開鍵は、プロジェクトのSettings -> Deploy KeysAdd deploy keyで登録します。秘密鍵はSettings -> SecretsAdd a new secretで登録します。Secret はMY_ACTIONS_DEPLOY_KEYという名前で登録しておくことにします。

  • 公開鍵の登録

../../_images/deploy_key.png ../../_images/deploy_key_success.png
  • 秘密鍵の登録

../../_images/action_key.png ../../_images/action_key_success.png

GitHub Actions の設定

GitHub Actions のワークフローを設定します。yaml ファイルは以下のmain.ymlのようになります。

警告

注意点として Deploy Keys を用いてコミットする場合、GitHub Actions 上で無限ループになる可能性があります。つまり GitHub Actions でコミットしたイベントをトリガーにして、次の GitHub Actions のワークフローを呼び出してしまうことです。GITHUB_TOKENを用いてコミットする場合は無限ループは発生しません、そうでない場合に無限ループになるのは GitHub Actions の仕様によるものです。こちらに GitHub Staff による回答があります。

無限ループを回避する方法の一つとして、GitHub Actions でコミットしたときの条件では GitHub Actions のワークフローが実行されないように制御する方法があります。以下のワークフローの設定ではif: "!contains(github.event.head_commit.message, 'auto rebuilding site')"として無限ループにならないようにしています。

上記の GitHub Actions の設定を実施しておくと GitHub リポジトリにコミットするときにワークフローが実行されます。以下のような結果を見ることができます。

../../_images/github_action_success.png

また参考までに GitHub Actions のデプロイのログの一部を載せておきます。

../../_images/github_action_success_log.png