はじめに

いくつかのプロジェクトにてSwaggerを利用した、API仕様書の運用をしています。
エンドポイントの追加・変更などがあった場合に、ドキュメントの更新を忘れがちなので、github上でPRを作成した際に、swaggerドキュメント生成のためのコマンドを自動実行し、差分があった場合はPR上にコメントするようなフローを作成しました。

使用言語及びライブラリは以下。
https://github.com/swaggo/gin-swagger

	github.com/swaggo/gin-swagger v1.3.3
	github.com/swaggo/swag v1.7.8

前提として、DockerfileやMakefile等でSwaggerドキュメントの生成ができている状態とします。
(各種ライブラリなどで設定方法・実行方法は違うと思うので、Swaggerの設定部分については割愛します。)

実行ファイル

全体の設定ファイルです。以下で一つ一つ見ていきます。
PRのオープン・プッシュのイベントでトリガーされます。

pr_pushed.yml

name: pr_pushed

on:
  pull_request:
    types: [opened, synchronize]
    branches: [develop]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          ref: ${{ github.event.pull_request.head.ref }}

      - name: exec swagg
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          make swag

          if ! git diff --exit-code --quiet
          then
            git config --global user.name "${GITHUB_ACTOR}"
            git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"

            git add .
            git commit -m "regenerated swagger by github actions"

            git push

            gh pr comment ${{ github.head_ref }} -b "swagger が更新されました"
          fi

checkout

- uses: actions/checkout@v3
  with:
    ref: ${{ github.event.pull_request.head.ref }}

最終的に、PRのブランチに対して、pushを行うためcheckoutブランチをrefで指定します。
（余談ですが指定なしの場合は、デフォルトブランチが指定されるそうです。）

# The branch, tag or SHA to checkout. When checking out the repository that
# triggered a workflow, this defaults to the reference or SHA for that event.
# Otherwise, uses the default branch.
ref: ''

差分を検知

if ! git diff --exit-code --quiet

Swaggerドキュメント更新を実施後、差分が無い場合は、commit時にエラーになるため、git diff --exit-code --quietによって、制御します。--exit-codeにより、差分があれば処理が終了するため、否定系!をつけておきます。

commitとpush

git config --global user.name "${GITHUB_ACTOR}"
git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"

git add .
git commit -m "regenerated swagger by github actions"

git push

通常と同じ流れでcommitしてpush。
GITHUB_ACTORはPRを行ったユーザーとなるので、userに設定することで、自動的にcommitログにも追加されます。

gh pr comment ${{ github.head_ref }} -b "swagger が更新されました"

PRへのコメントに対しては、githubCLIが使用できるので、そちらを利用します。
GH_TOKENという名称で、値はsecrets.GITHUB_TOKENを使用します。別途PAT(PersonalAccessToken)も使用できそうです。
対象のブランチは github.head_refを使用して特定します。
※こちらはPullRequestEventでしか取得できないので、他のイベントの場合は注意。

参考

https://dev.classmethod.jp/articles/how-to-get-a-ref-branch-within-a-workflow-execution-in-github-actions/
https://cli.github.com/manual/gh_pr_comment
https://github.com/actions/checkout
https://yoshiori.hatenablog.com/entry/2021/12/08/220839
https://zenn.dev/lollipop_onl/articles/eoz-gha-push-diffs

GithubActionsでSwaggerドキュメントを自動更新して、PRへコメントをつける

はじめに

実行ファイル

checkout

差分を検知

commitとpush

コメント

参考