gh-extension と aqua で作る GitHub Actions アクション

gh-extension と aqua で作る GitHub Actions アクション 2025/10/23 CI/CD Test Night #8 © DeNA Co., Ltd. 1

自己紹介 ● しらやなぎ たかずみ ● ずみっくす（@srz_zumix） ● https://github.com/srz-zumix ○ 2011年くらい〜 ○ C++ Testing Framework ○ CI/CD 関係とか ○ 最近は GitHub Actions © DeNA Co., Ltd. 2

• https://github.com/srz-zumix

作った GitHub Actions のアクション gh repo list --topic actions --visibility=public © DeNA Co., Ltd. 3

• https://github.com/search?q=owner:srz-zumix topic:actions&type=repositories&s=updated&o=desc

よく使ってるアクション ● post-run-action ○ Post 処理で run 相当の処理が可能なアクション ○ Composite Action で Post 処理するのに便利 ● retry-run-action ○ リトライ可能な run アクション ● workspace-git-config-action ○ includeIf でパス限定の git config をセットするアクション ○ Self-hosted runner 向けを想定 © DeNA Co., Ltd. 4

• https://github.com/srz-zumix/post-run-action
• https://github.com/srz-zumix/retry-run-action
• https://github.com/srz-zumix/workspace-git-config-action

よく使ってるアクション ● kamidana-action ○ Jinja2 template アクション ○ Slack 通知の payload 作成などに利用 ● gh-pr-ls-files ○ checkout なしで PR のファイルリスト取得 ○ Added/Deleted などでフィルター可能 ● labeler-action ○ 今日紹介するアクション © DeNA Co., Ltd. 5

• https://github.com/srz-zumix/kamidana-action
• https://github.com/srz-zumix/gh-pr-ls-files
• https://github.com/srz-zumix/labeler-action

labeler-action ● https://github.com/actions/labeler と同等のアクション ○ 設定ファイルのパス・ブランチ条件で自動でラベル付け ● なぜ同じようなアクションを自作したのか？ ○ 過去の PR に対してラベル付けしようとしたところ head-branch/base-branch 条件が pull_request イベント時 にしか使えないことが発覚 ○ バグ修正ついでに機能拡張して個人的に使いやすいものを作成 https://github.com/actions/labeler/pull/873 修正PRは出してはいるがマージされてないので自作した © DeNA Co., Ltd. 6

• https://github.com/actions/labeler
• https://github.com/actions/labeler/pull/873

labeler-action の構成
● gh-extension + aqua
● composite action
○ action.yml

● aqua でインストール
● アクションはツール
の呼び出しだけする

steps:
- uses: aquaproj/aqua-installer@ea51… # v4.0.3
with:
working_directory: ${{ github.action_path }}
- name: gh-labeler-kit path
id: gh-labeler-kit
shell: bash
env:
AQUA_POLICY_CONFIG: aqua-policy.yaml
run: |
gh-label-kit --version
echo "path=$(aqua which gh-label-kit)">>"${GITHUB_OUTPUT}"
working-directory: ${{ github.action_path }}
- name: Labeler
shell: bash
run: |
"${GH_LABELER_KIT}" labeler …

※ スライド掲載用に大幅に省略しています
© DeNA Co., Ltd.

7

• https://github.com/srz-zumix/labeler-action/blob/main/action.yml

gh-extension © DeNA Co., Ltd. 8

gh-extension とは？ ● GitHub CLI（gh）の拡張機能 ● 誰でも作成、使用ができる gh のカスタムコマンド ○ GitHub CLI 拡張機能の使用 ○ GitHub CLI 拡張機能の作成 ● 個人的に使っている拡張機能 ○ https://github.com/seachicken/gh-poi ○ https://github.com/k1LoW/gh-do ○ https://github.com/k1LoW/gh-triage © DeNA Co., Ltd. 9

• https://docs.github.com/ja/github-cli/github-cli/using-github-cli-extensions
• https://docs.github.com/ja/github-cli/github-cli/creating-github-cli-extensions
• https://github.com/seachicken/gh-poi
• https://github.com/k1LoW/gh-do
• https://github.com/k1LoW/gh-triage

作った gh-extension gh repo list --topic gh-extension --visibility=public © DeNA Co., Ltd. 10

• https://github.com/search?q=owner:srz-zumix topic:gh-extension&type=repositories&s=updated&o=desc

gh-extension として labeler 機能を作成 ● https://github.com/srz-zumix/gh-label-kit ○ ラベル関係の API を扱う gh-extension ○ Organization のデフォルトラベルを扱いたくて作り始めた ■ API なくて一旦あきらめ中 ■ copy / sync コマンドで代用 ● gh label-kit labeler サブコマンドで actions/labeler 機能を実装 ○ gh-extension を選択した理由は当初はあまりなかった ○ label-kit だしこれに実装しようくらいの判断で決めた © DeNA Co., Ltd. 11

• https://github.com/srz-zumix/gh-label-kit

gh-extension の公開 ● gh-extension の実体は gh-label-kit のように gh- で始まる スクリプト or プリコンパイル済み実行ファイル ● gh extension install でインストール ○ スクリプトの場合は内部的に checkout ■ --pin 指定がない場合はデフォルトブランチ ○ プリコンパイルの場合は Releases からダウンロード ■ © DeNA Co., Ltd. –-pin 指定がない場合は latest 12

gh-extension の公開 ● スクリプトの場合は push するだけ ● プリコンパイルの場合はリリースに OS / Arch ごとの attachments をアップロードする ○ https://github.com/cli/gh-extension-precompile ○ プリコンパイル用アクションで簡単にリリース可能 ● gh-label-kit は Go のプリコンパイル済みとして開発 ○ どの方法でも良いが、以降この資料は gh-label-kit の構成で説明 © DeNA Co., Ltd. 13

• https://github.com/cli/gh-extension-precompile

この時点でのアクション開発の想定 ● ランナー環境には gh がプリインストールされている ○ Self-hosted runner だとそうじゃないかもしれないがレアケース ● gh extension install で簡単にインストールできる ● あとは拡張機能のラッパーとして action.yml 用意すれば OK 簡単！ © DeNA Co., Ltd. 14

aqua © DeNA Co., Ltd. 15

aqua とは？ ● https://github.com/aquaproj/aqua より引用 ○ Declarative CLI Version Manager written in Go. © DeNA Co., Ltd. ■ Switch tool versions per project ■ Unify tool versions and how to install in your teams and CI ■ Continuous update by Renovate ■ Lazy Install ■ Ecosystem by Registry ■ Secure ■ Easy to use 16

• https://github.com/aquaproj/aqua

aqua を使い始めた理由 ● gh-extension のインストールパスが指定できなかったため ○ 常駐型の Self-hosted runner 運用で困る ○ なんで困るのかは過去の発表を参照してください ■ GitHub Actions Self-hosted runner を 3年間運用したこれまでとこれ から 〜 分散するワークフローと管理の課題 | ドクセル ■ GitHub Actions x Unity プロジェクトの裏側 | ドクセル ● aqua は AQUA_ROOT_DIR でパス指定可能 ● aqua 自体が便利だということを知っていた © DeNA Co., Ltd. 17

• https://www.docswell.com/s/DeNA_Tech/ZQXJ4Y-GDM64-GitHub-Actions-Self-hosted-runner
• https://www.docswell.com/s/DeNA_Tech/ZYDNP3-2024-08-05-134204

aqua でインストール
● gh-extension リポジトリをローカルレジストリとして登録
packages:
- type: github_release
repo_owner: srz-zumix
repo_name: gh-label-kit
description: gh extension of github label api
asset: "{{.OS}}-{{.Arch}}"
format: raw

© DeNA Co., Ltd.

18

aqua でインストール ● ポリシーでローカルレジストリを許可 registries: - type: standard ref: semver(">= 3.0.0") - name: local type: local path: aqua-registry.yaml packages: - registry: standard - registry: local © DeNA Co., Ltd. 19

aqua でインストール ● ローカルレジストリを参照してインストール registries: - type: standard ref: v4.427.0 # renovate: depName=aquaproj/aqua-registry - name: local type: local path: aqua-registry.yaml packages: - name: suzuki-shunsuke/[email protected] tags: - dev - name: srz-zumix/[email protected] registry: local tags: - dev - action © DeNA Co., Ltd. 20

アクションでポリシーを適用
● アクションでポリシーを適用するには
AQUA_POLICY_CONFIG 環境変数でパス指定する必要がある
● 必要なのは実際にインストールするとき
- name: gh-labeler-kit path
id: gh-labeler-kit
shell: bash
env:
AQUA_POLICY_CONFIG: aqua-policy.yaml
run: |
gh-label-kit --version
echo "path=$(aqua which gh-label-kit)">>"${GITHUB_OUTPUT}"

© DeNA Co., Ltd.

21

なぜ AQUA_POLICY_CONFIG が必要なのか ● アクションのセットアップ挙動 ○ ${{ github.action_path }} にリポジトリの内容が展開されます ○ git clone ではなく git archive が展開される ○ .git ディレクトリがなく git ワークスペースではない ● aqua は .git ディレクトリがないと規定のポリシーファイルを 読み込まない © DeNA Co., Ltd. 22

ちなみに ● git archive されるので .gitattributes の export-ignore が効く ○ export-ignore 指定すると archive に含まれない ○ つまり、アクション実行に必要なファイルのみにできる ○ ブログズミ: 【GitHub Actions】export-ignore でアクションのサ イズを小さくする小技 ○ export-subst なんてのもある ■ uses: srz-zumix/labeler-action@$Format:%H$ ■ アクションのコミットハッシュを動的に展開できたけど何に使える のかはわからん © DeNA Co., Ltd. 23

• https://srz-zumix.blogspot.com/2025/09/github-actionsexport-ignore.html

完成 して気付いたことが・・・ © DeNA Co., Ltd. 24

gh-extension + aqua のいいところ © DeNA Co., Ltd. 25

Composite Action のメリット ● node 非依存 ● 定期的にやってくる node バージョン更新 ○ https://github.blog/changelog/2025-09-19-deprecation-of-node20-on-github-actions-runners/ ○ https://github.blog/changelog/2024-03-06-github-actions-all-act ions-will-run-on-node20-instead-of-node16-by-default/ © DeNA Co., Ltd. 26

• https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/
• https://github.blog/changelog/2024-03-06-github-actions-all-actions-will-run-on-node20-instead-of-node16-by-default/

gh-extension のメリット ● ローカルで同じことができる ○ action.yml と同じことをやりたいときが割とある ○ Jenkins のときも処理はスクリプトに書いて、ジョブは呼び出す だけにしろと言われて育てられました ○ aqua でもその便利さを実感している ■ Unify tool versions and how to install in your teams and CI ● デバッグもしやすい © DeNA Co., Ltd. 27

gh-extension のメリット ● AI Ready である ○ CLI で実行できるのは AI 利活用の上でもメリットがある ○ 特に Git/GitHub に関係のある機能であれば gh-extension として 実装するメリットがある ● gh extension install で簡単に使える ○ aqua でも良いが gh extension install だけで使えるのは楽 © DeNA Co., Ltd. 28

gh-extension + aqua のメリット ● 手間をかけずにセキュアになる ○ Attestations に簡単に対応できる ■ アーティファクトの構成証明を使用して構築の実績を確立する GitHub Docs ○ ついでに Immutable Releases も有効にしておきましょう ■ © DeNA Co., Ltd. Immutable releases - GitHub Docs 29

• https://docs.github.com/ja/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations
• https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/immutable-releases

gh-extension + aqua のメリット
● gh-extension 側の対応

© DeNA Co., Ltd.

permissions:
contents: write
id-token: write
attestations: write
env:
RELEASE_TAG: ${{ inputs.ref || github.ref }}
GH_TOKEN: ${{ github.token }}
steps:
- uses: actions/checkout@v5
with:
persist-credentials: false
- uses: cli/gh-extension-precompile@9e2237c… # v2.1.0
with:
generate_attestations: true
go_version_file: go.mod
release_tag: ${{ env.RELEASE_TAG }}
- if: inputs.publish
run: gh release edit --draft=false "${RELEASE_TAG}"
30

gh-extension + aqua のメリット
● aqua 側の対応
packages:
- type: github_release
repo_owner: srz-zumix
repo_name: gh-label-kit
description: gh extension of github label api
asset: "{{.OS}}-{{.Arch}}"
format: raw
github_artifact_attestations:
signer_workflow: srz-zumix/gh-label-kit/.github/workflows/release.yml

© DeNA Co., Ltd.

31

aqua のメリット ● aqua がそもそも便利 ● アクションで gh-extension をインストールするだけでなく、 gh-extension を開発する上でのツール管理として使える © DeNA Co., Ltd. 32

まとめ ● ローカルでも実行可能なアクションを開発するのがオススメ ● gh-extension + aqua はその構成としてオススメ © DeNA Co., Ltd. 33

© DeNA Co., Ltd. 34