Github PagesでCI/CDのレポートサイトの構築方法

はじめに

AIでの開発が盛んになる中で、開発を効率的に進めるためには、さまざまなデータの取得とともにデータの可視化が重要です。そのためのGithubでレポートサイト構築の手順を示します。
社内でGitHub Enterpriseが利用可能になったため、そのメリットを活かした方法をまとめました。

Github Pagesで作成するメリット

• Github内ですべて完結します。他の環境に依存しません。制限としては、エンタープライズエディションでないと、プライベート公開ができません。（現在）
  • 標準化しやすい。
• 閲覧権限の付与がリポジトリのアクセス権と同じにできるので、セキュリティリスクが低い。管理も楽
  • Basic認証で運用すると、セキュリティ的に弱くなりがち、リスクがある。ログイン処理を作るとユーザ管理がめんどくさい。
  • Githubと同じ認証を使えるのは、高いセキュリティを保てます。2段階認証なども行えます。
  • カバレッジなど表示する時に、コードが出るので、セキュリティを担保したいところ。
• 開発担当者のみで自由に構築可能です。インフラ担当者にいろいろ用意して管理して、などがいりません。

Github Pagesでレポートサイトの構築ポイント

• 一番重要なのは、エンタープライズエディションでないと、プライベートでの公開ができません。
• 開発用のコードリポジトリと、 Github Pagesのリポジトリを分けます。蓄積されるレポートはコードと切り離して管理します。開発用のリポジトリはマルチで問題なし。役割をリポジトリで分離しています。
• リポジトリ間で、repository_dispatchでフロー呼び出し、処理します。
• ファイル内容の受け渡しは、アーティファクトで行います。
• 別のリポジトリのフロー呼び出しになるので、personal access tokenが必要になります。classicでも動きます。
• Github PagesのリポジトリはPagesの設定で、deploy from branchで設定する。ブランチからの公開なので、部分的な更新を可能にしています。
• レポートの生成は、プルリク作成更新時に、プルリクに対するレポートを作成します。またプルリクマージ時にレポートは削除しています。最新のレポートはlatestで保持するようにしています。（プロジェクトに合った作成を）
• 公開手順
  • Github Actionsでビルド、テスト等で公開するレポートを作成し、それをアーティファクトに保存する。
  • 作成したアーティファクトからGithub Pagesで公開するためのフローを呼び出しを行います。呼び出しにはアーティファクト名などをフローに送信する。
  • Github Pagesで公開するためのフローは、アーティファクトを受け取り、リポジトリ名/アーティファクト名/プルリク番号でレポートを配置します。プルリクに対するレポートとして見たいため。またリポジトリごと、アーティファクトごと別々にレポートが閲覧できます。
  • 公開のためにjob内でページリポジトリに対して、自動でレポートファイルのコミット、プッシュを行う。それにより部分的な、リポジトリの更新を行う。
  • その後、Github Pagesがサイトを公開してくれます。

個々の処理の設定方法

生成されたレポートをアーティファクトに保存する

• actions/upload-artifactを使用します。
• pathに生成したレポートのディレクトリを指定します。カバレッジ、テスト結果など、さまざまなHTMLレポートをディレクトリにまとめておきます。
• nameにアーティファクト名を指定します。自分でつけます。

    - name: Upload artifacts reports
      uses: actions/upload-artifact@v4
      if: always()
      with:
        name: XXXXXX-reports-frontend
        path: |
          report-site/

レポートが生成されたことをページリポジトリに伝える

• repository_dispatchを使用します。
• peter-evans/repository-dispatchで起動してくれます。受け取り側のアクションが動きます。
• event-typeにイベント名を記述します。自分で定義します。フロー名ではありません。
• client-payloadに送信する形式のJSONを記述します。自分で定義します。
• 事前にtokenを発行しsecretsに指定しておきます。ここでは詳しく説明しません。
• repositoryはページリポジトリ名を記述します。組織/リポジトリです

      - name: Send repository_dispatch to publishing repo
        uses: peter-evans/repository-dispatch@v4
        with:
          token: ${{ secrets.CROSS_REPO_TOKEN }}
          repository: XXXXXOrg/XXXRepo
          event-type: publish-report
          client-payload: |-
            {
              "source_owner": "${{ github.repository_owner }}",
              "source_repo": "${{ github.event.repository.name }}",
              "run_id": "${{ github.run_id }}",
              "artifact_name": "上でつけたアーティファクト名",
              "pr_number": "${{ github.event.pull_request.number }}",
              "commit_sha": "${{ github.sha }}",
              "ref": "${{ github.ref }}"
            }

コメントとしてレポートページのURLをプルリクに記述する。

• リンクをプルリクページにつけることで、手間なくページを開けます。
• プルリク番号が付与されるので、それを加味したURLを作成します。
• 自由にコメントを生成してください。

  comment-report-url:
    # コメントを追加するのは新規PR作成時のみ
    if: ${{ github.event.action == 'opened' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - name: Comment Report URL on PR
        uses: peter-evans/create-or-update-comment@v4
        with:
          issue-number: ${{ github.event.pull_request.number }}
          body: |
            レポートリンク
            [report ALL](${{ env.PAGES_BASE_URL }}/${{ github.event.repository.name }}/${{ env.ARTIFACT_NAME }}/${{ github.event.pull_request.number }}/report-site/)
            [unit test report](${{ env.PAGES_BASE_URL }}/${{ github.event.repository.name }}/${{ env.ARTIFACT_NAME }}/${{ github.event.pull_request.number }}/report-site/junit-report/)
            [postman test report](${{ env.PAGES_BASE_URL }}/${{ github.event.repository.name }}/${{ env.ARTIFACT_NAME }}/${{ github.event.pull_request.number }}/report-site/postman/)
            [code coverage report](${{ env.PAGES_BASE_URL }}/${{ github.event.repository.name }}/${{ env.ARTIFACT_NAME }}/${{ github.event.pull_request.number }}/report-site/jacocoHtml/)

PUSHのときにプルリク番号を取得する

• Github Actionsにて、プッシュして処理されるフローには、プルリクにてマージされたプルリク番号を直接取得することはできません。
• プッシュした時に、プルリクの確認は終わったはずなので、プルリク自体のレポートを削除するために、番号を取得します。（プロジェクトのプロセスによっては変更してください）
• uses: jwalton/gh-find-current-pr@masterを使用してプルリク番号を取得します。
• pull-requests: readをつけてください。

          # 追加: コミットに関連付く PR 番号取得
      - name: Find associated PR
        uses: jwalton/gh-find-current-pr@master
        id: extract_pr
        with:
          state: all

ページサイト構築側の設定

• ページ側のリポジトリにワークフローを作成しておきます。
• repository_dispatch:types: [publish-report]で送信側で定義したイベント名を指定しておきます。
• permissionsコミットなどを実行するため、権限を設定します。
• concurrencyコミット＆プッシュするので、Git操作時にマージ不可にならないように、順次実行にしておきます。
• echo parameterで送信されたパラメータをでデバッグ用に出力しておきます。
• actions/download-artifactでレポートを受け取ります。
• gitコマンドで、pushまで行います。

name: Deploy Report to Pages

on:
  repository_dispatch:
    types: [publish-report]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: write
  pages: write
  id-token: write
  actions: read

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          ref: main
      - name: echo parameter
        run: |
          echo RUN_ID:${{ github.event.client_payload.run_id }}
          echo PR_NUMBER:${{ github.event.client_payload.pr_number }}
          echo SOURCE_REPO:${{ github.event.client_payload.source_repo }}
          echo ARTIFACT_NAME:${{ github.event.client_payload.artifact_name }}

      - name: Download pages artifact
        uses: actions/download-artifact@v4
        with:
          name: ${{ github.event.client_payload.artifact_name }}
          repository: XXXXXXXXorg/${{ github.event.client_payload.source_repo }}
          path: docs/${{ github.event.client_payload.source_repo }}/${{ github.event.client_payload.artifact_name }}/${{ github.event.client_payload.pr_number }}
          github-token: ${{ secrets.CROSS_REPO_TOKEN }}
          run-id: ${{ github.event.client_payload.run_id }}

      - name: Setup Git
        run: |
          git config --global user.name 'github-actions[bot]'
          git config --global user.email 'github-actions[bot]@users.noreply.github.com'

      - name: Add and Commit docs files
        run: |
          git add docs/
          git commit -m "Add report files to docs"

      - name: Copy to latest and Commit
        run: |
          rm -rf docs/${{ github.event.client_payload.source_repo }}/${{ github.event.client_payload.artifact_name }}/latest
          cp -r docs/${{ github.event.client_payload.source_repo }}/${{ github.event.client_payload.artifact_name }}/${{ github.event.client_payload.pr_number }} docs/${{ github.event.client_payload.source_repo }}/${{ github.event.client_payload.artifact_name }}/latest
          git add docs/${{ github.event.client_payload.source_repo }}/${{ github.event.client_payload.artifact_name }}/latest
          git commit -m "Publish report as latest"
          git push origin main

プルリクマージ後の古いレポートの削除処理

• repository_dispatch:types: [delete-report]削除用のイベントを記述します。
• その他上記と同じ様にgitの処理を記述します。

  repository_dispatch:
    types: [delete-report]
...

まとめ

• 何度もいいますが、エンタープライズでないとできません。または全体に公開する。
• 個々の機能の実装は、色々なサイトで説明しているが、全体として、仕組みを考えて実装してみました。
• 一度作ってしまえば簡単にいろいろレポートを追加できるので良かった。
• ディレクトリ構造で複数のプルリクの並行にも対応しています。
• 削除処理とlatestでどんどんレポートが溜まるのを防いでいます。
• セキュリティが担保でき、そのメンテナンスがいらないので、安心です。
• 'Resource not accessible by integration'が出たときは、jobに対するpermissionsを追加してみてください。

今後の拡張

• テスト件数推移やカバレッジ推移などなど必要なデータの蓄積をGithub Actionsを絡めてグラフ化したい。
• いろいろなメトリクスも出せるのではないか