GitHub ActionsによるDoxygen文書のGitHub Pageへのデプロイとパーミッション設定

GitHubリポジトリへのプッシュ/マージ時にGitHub ActionsでDoxygenを走らせ、HTML文書をGitHub Pageにデプロイするようにしました。これで最新のAPIドキュメントを自動的に公開できます。

さて、このアクションは多くの方が試しており、ネット上に様々な情報があります。おかげで見よう見まねで何とか形にすることができました。が、IT分野ならではの変化の速さのため、古い情報をいくつもかき分けてようやく正解にたどり着けた有様でした。以下、メモとして情報を残しておきます。

doxygen-github-pages-action

doxygen-github-pages-actionはDenverCoder1氏がGitHubマーケットプレースに公開しているアクションで、GitHub Actionsの中でDoxygen文書を生成してGitHub Pageにデプロイできます。これにより、Doxygenの出力であるHTMLファイルをそのままWEBサーバーから公開できます。

さて、このアクションのレポジトリには参考としてdoxygen-gh-pages.yamlが掲載されています。

name: Doxygen GitHub Pages Deploy Action

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: DenverCoder1/doxygen-github-pages-action@v2.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

残念ながらこのファイルをそのまま使ってもデプロイはエラーで終了します。

解決策

この問題は以下のようにpermissions: を明示的に宣言することで解決します。

name: Doxygen GitHub Pages Deploy Action

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: DenverCoder1/doxygen-github-pages-action@v2.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

アップデート 2024-Sep-26

permissions: から pages: を削除しました。この権限はサイトをビルドするときのみ必要です。このアクションではDoxygenが生成したHTLMファイルを単にアップロードしているだけなので、この権限無しでも動作します。

何が起きているのか

この問題の原因は、GitHub ActionsのGITHUB_TOKENの初期権限が、read/writeからreadに変更されたことです。

GitHubはリポジトリや各種リソースへのアクセスに対して、トークンを使って安全性を確保しています。習慣的に我々はそういった作業にパスワードを使うことを想像します。しかしながら煩雑に起きるリソースアクセスにパスワードを使うことは漏洩リスクの増大につながります。トークンは権限を細かく絞ることができるため、トークンが漏洩しても被害を最小に抑えることができます。

GITHUB_TOKENはGitHub Actionsが使う環境変数（特殊なグローバル変数）で、GitHub Actionsのワークフローが起動されたときに作られてリポジトリごとに決められた権限を与えられます。そしてワークフローが終了するとこの環境変数も削除されます。したがって外部漏洩の心配はありません。

先のGitHubブログではこのGITHUB_TOKENの権限の初期値がより厳しいものになったと案内しています。セキュリティを設定を安全な方向に倒したことで、それまで動いていたサンプルが動かなくなったわけです。

上で紹介したYAMLの変更はpermissionsを指定することで、一時的にGITHUB_TOKENにより広い権限を与えてこの問題を解決しています。この方法のほかにリポジトリのGITHUB_TOKEN権限設定を緩くする方法もありますが、permissionsを指定する方がより局所的であるため安全と考えられます。

試験とフィードバック

手元でリポジトリを作って実験し、permissionsの設定で問題が解決することを確認済みです。

また、この件については開発者に対してプルリクエストを提出しています。

アップデート 2024-Sep-27

上記プルリクエストがmainブランチにマージされました。