github actionsでrelease時にzipファイルを生成して関連情報をreleaseの本文（body）に表示

背景

github actionsとはgithubに対する操作に応じて処理を組み込める仕組みです。

KiCadのAddonとして公開するzipファイルにreadmeなどのファイルを含めるとエラーになるため、github actionを利用してreleaseしたら自動で必要なzipファイルが生成されるようにしてみました。
また、addon登録時にzipファイルのshaや大きさが必要になるので、それをreleaseの本文に記す処理も作りました。

備忘録を兼ねてgithub actionで分かったことを記事に残します。

使ったもの

• githubアカウント
• gitを使えるPC

作ったwork flowファイルの全体像

work flowファイルを配置するとgithub actionで認識されて処理が行われます。
自分がgithubにアップロードしているファイルはこちらです。

https://github.com/asukiaaa/gerber_to_order/blob/master/.github/workflows/create-archive.yml

解説のために記事を書いている時点での上記ファイルの内容を貼り付けます。

.github/workflows/create-archive.yml

name: Create Archive

on:
  release:
    types: [published]

jobs:
  build:
    name: Create Archive
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Create zip file
        run: zip kicad-addon metadata.json -r plugins -r resources
      - name: Upload assets
        id: upload-assets
        uses: softprops/action-gh-release@v1
        with:
          files: kicad-addon.zip
      - name: Put zip info to Release.txt
        run: |
          echo "\`\`\`json" >> Release.txt
          echo "{" >> Release.txt
          echo "  \"download_size\": $(stat --printf=%s kicad-addon.zip)," >> Release.txt
          echo "  \"download_sha256\": \"$(sha256sum kicad-addon.zip | cut -d ' ' -f 1)\"," >> Release.txt
          echo "  \"download_url\": \"${{ fromJSON(steps.upload-assets.outputs.assets)[0].browser_download_url }}\"," >> Release.txt
          echo "  \"install_size\": $([[ "$(zipinfo -t kicad-addon.zip)" =~ ^[0-9]+\ files,\ ([0-9]+)\ bytes.*$ ]]; echo ${BASH_REMATCH[1]})" >> Release.txt
          echo "}" >> Release.txt
          echo "\`\`\`" >> Release.txt
      - name: Update body of release
        uses: softprops/action-gh-release@v1
        with:
          append_body: true
          body_path: Release.txt

上記のファイルを配置してgithubでreleaseを実施すると下記のreleaseが生成されます。

• metadata.json、resources、pluginsを含んだkicad-addon.zipをreleaseのファイルとしてダウンロード可能
• releaseの本文にkicad-addon.zipのsha256、圧縮状態の大きさ、展開時の大きさ、ダウンロードurlを意味するjson情報を表示

上記の処理でzipファイルと本文の情報が追加されたreleaseがこちらです。

https://github.com/asukiaaa/gerber_to_order/releases/tag/1.0.0

各行を解説します。

ファイル名とnameを設定

.github/workflows/create-archive.yml

name: Create Archive

リポジトリの.github/workflowsにymlを配置するとgithubが認識してくれます。
任意の文字列を割り当て可能です。
処理を意味する名前にしておくとログを見たときに分かりやすいです。

actionのログで名前やファイル名が表示されます。

参考:
name - github workflow

onで起点を設定

on:
  release:
    types: [published]

actionを実行する起点をonで記述します。
今回はrelease実施時に処理したいので、releaseを指定します。
on: releaseとするとpublilshed、created、releasedの起点で3つの処理がほぼ同時に開始されて、actionのログが冗長になります。
さらにon: releaseだと削除時にdeletedの起点でも実行されます。
release時に一度だけ実施されたら良いので、releaseのtypeとしてpublishedを指定しています。

参考:
on - github workflow
Action run being trigger multiple times #25029

jobsで実行環境を指定

jobs:
  build:
    name: Create Archive
    runs-on: ubuntu-latest

今回は参考にしたymlファイルで利用されていたbuildという文字列をjob_idとして使いました。

job.<job_id>.runs-onでworkflowを実行するマシンの種類を選べます。

GitHub ホステッド ランナーの選択

windows、mac、linuxのいくつかのバージョンを指定できます。
今回はubuntu-latestとしてubuntuの最新環境で実行する設定にしました。

jobのnameはログで表示されます。

参考:
jobs.<job_id>.runs-on - github workflow

stepsで具体的な処理を記載

jobs:
  build:
    steps:
      ..

定義済みのactionを読んだり、コマンドを実行したりなど、具体的な処理をstepとして定義していきます。

参考:
jobs.<job_id>.steps - github workflow

checkoutで実行対象のファイルを配置

      - uses: actions/checkout@v3

jobsはリポジトリのファイルが配置されていない状態で動き始めるので、まずは定義済みのcheckout処理を呼び出して関連ファイルを配置します。

複雑なcheckout処理をしたい場合は下記actions/checkoutのreadmeやissueが参考になると思います。

参考:
https://github.com/actions/checkout

runでzipファイルを作成

      - name: Create zip file
        run: zip kicad-addon metadata.json -r plugins -r resources

kicad-addonの仕様としてzipでまとめる対象であるmetadata.json、pluginsディレクトリ、resourcesディレクトリを指定してkicad-addon.zipを作成します。
runに記述したコマンドがjobs.<job_id>.runs-onで指定したマシンの非ログインシェルで実行されます。

参考:
jobs.<job_id>.steps[*].run - github actions

zipファイルをreleaseのassetファイルとしてアップロード

      - name: Upload assets
        id: upload-assets
        uses: softprops/action-gh-release@v1
        with:
          files: kicad-addon.zip

softprops/action-gh-releaseを利用してreleaseのassetファイルとして作成したkicad-addon.zipをアップロードします。
参考にしたymlファイルでactions/upload-release-assetを利用しているものがいくつかありましたが、それは既にアーカイブされて保守されない状態にあるため、それのreadmeで紹介されているsoftprops/action-gh-releaseを使うのが良いです。

後の処理で情報を参照したいので、idでupload-assetsという名前をstepに付けています。

releaseの本文（body）に表示する情報を収集

      - name: Put zip info to Release.txt
        run: |
          echo "\`\`\`json" >> Release.txt
          echo "{" >> Release.txt
          echo "  \"download_size\": $(stat --printf=%s kicad-addon.zip)," >> Release.txt
          echo "  \"download_sha256\": \"$(sha256sum kicad-addon.zip | cut -d ' ' -f 1)\"," >> Release.txt
          echo "  \"download_url\": \"${{ fromJSON(steps.upload-assets.outputs.assets)[0].browser_download_url }}\"," >> Release.txt
          echo "  \"install_size\": $([[ "$(zipinfo -t kicad-addon.zip)" =~ ^[0-9]+\ files,\ ([0-9]+)\ bytes.*$ ]]; echo ${BASH_REMATCH[1]})" >> Release.txt
          echo "}" >> Release.txt
          echo "\`\`\`" >> Release.txt

Release.txtというファイルに、releaseの本文（body）に表示したい情報を記述します。
zipファイルの大きさ（download_size）、zipファイルのsha256（download_sha256）、zipファイルのurl（download_url）、zipファイル展開後の大きさ（install_size）を求め、json形式で表記しました。

注意点として改行を挟むと定義したシェルの変数を参照できなくなるため、変数を使う処理は「;」などを利用して1行で記述します。

          echo "  \"download_url\": \"${{ fromJSON(steps.upload-assets.outputs.assets)[0].browser_download_url }}\"," >> Release.txt

action-gh-releaseの情報を呼び出すためにfromJSON(steps.<step id of action-gh-release>.outputs.assets)を記述し、それを利用してアップロードしたkicad-addon.zipのurlを取得しています。

          echo "  \"install_size\": $([[ "$(zipinfo -t kicad-addon.zip)" =~ ^[0-9]+\ files,\ ([0-9]+)\ bytes.*$ ]]; echo ${BASH_REMATCH[1]})" >> Release.txt

zip展開後の大きさのみを出力するコマンドオプションが分からなかった（無い？）のでzipinfoの出力から正規表現で展開後の大きさ情報を抽出しています。
他に便利なコマンドがあれば、コメントなどで共有していただけると嬉しいです。

          echo "\`\`\`json" >> Release.txt
          echo "{" >> Release.txt

          echo "}" >> Release.txt
          echo "\`\`\`" >> Release.txt

本文貼り付け時に見やすくするためjson形式の表示と宣言しています。

参考:
outputs - action-gh-release
Bashで正規表現マッチした文字列を取り出す

releaseの本文（body）に情報を追加

      - name: Update body of release
        uses: softprops/action-gh-release@v1
        with:
          append_body: true
          body_path: Release.txt

再びsoftprops/action-gh-releaseを利用して今度はreleaseの本文（body）に情報を追記します。
先程のstepで作成したRelease.txtをbody_pathに指定すると、その内容がbodyに反映されます。
append_bodyをtrueにすると、bodyの上書きではなく、追記処理になります。

参考:
inputs - action-gh-release

作成したworkflowの解説は以上です。

終わり

github actionsのworkflowを利用して、releaseにzipファイルの追加と、releaseの本文（body）へのzipファイルの情報の追記を行えました。
手間と感じるrelease作業の一部を自動化出来て嬉しいです。

参考

今回作成したworkflowです。
https://github.com/asukiaaa/gerber_to_order/blob/master/.github/workflows/create-archive.yml

利用したactionです。
actions/checkout
softprops/action-gh-release

公式の構文解説です。
GitHub Actions のワークフロー構文

参考にしたymlファイルです。
https://github.com/firewood/iOSDC2020-Talk-Sample/blob/main/.github/workflows/release.yml
GitHub Actionsでリリースする