Custom GitHub Actions by Java

Java で作る
カスタム GitHub Actions
2022-06-19 (Sun) Tetsuya Morimoto

View Slide

2
Kazamori LLC © 2022
● 森本哲也 (もりもとてつや)
● 神戸市在住
● 　　カザモリ合同会社
○ 2019年12月に設立 (いま第4期目)
○ フルリモートワークで他社の開発のお手伝いをしている
● 課題管理 (課題管理システム) に関心がある
● 言語歴は Python → Java → Go をそれぞれ5年ほどの実務経験
● プログラミングや OSS 文化が好き
自己紹介

View Slide

3
目次
GitHub Actions とカスタムアクション
01.
Docker container action によるカスタムアクション
02.
Java アプリケーションと Docker イメージのビルド
04.
カスタムアクションの開発、テストやデバッグのコツ
05.
まとめ
06.
Java の CLI アプリケーションと Docker container action の境界
03.

View Slide

4
GitHub Actions と
カスタムアクション

View Slide

5
GitHub プラットフォーム上でソフトウェア開発のワークフロー自動化などを行うための機能
● 一般的な用途として CI/CD を実現するためのツールと理解しても概ね間違ってない
使い始めやすい理由がたくさんある
● 多くの開発者が GitHub リポジトリを利用している
● GitHub プラットフォームの様々なイベントをトリガーにできる
● 料金も安い (About billing for GitHub Actions から引用)
○ public リポジトリの利用は無料
○ private リポジトリではプロダクトごとに無料枠
■ GitHub Free : ストレージ 500MB、2,000時間まで無料
■ GitHub Team: ストレージ 2GB、3,000時間まで無料
■ …
GitHub Actions とは

View Slide

6
処理の単位として3段階ある
● ワークフロー (ファイル単位)
○ ジョブ (ホスト単位)
■ ステップ (スクリプト単位)
ステップが処理を記述する最小の単位になる
ステップ単位で処理を実行する外部モジュールをカスタムアクションと呼ぶ
最もよく使われているカスタムアクションに checkout がある
GitHub Actions のワークフローと実行単位
ワークフローは
YAML で定義
steps:
- uses: actions/checkout@v3
with:
ref: main

View Slide

7
現時点では3つの種別がある
● Docker container action ← 本稿の話題
○ Docker コンテナーでカスタムアクションを実装
○ あまり使われていないかも？マイナー？
● JavaScript action
○ JavaScript でカスタムアクションを実装する
○ GitHub 社の公式アクションの多くは JavaScript で実装されているようにみえる
■ サンプルコードも多く、ライブラリも提供されている
● Composite actions
○ 複数ステップからなるカスタムアクションを実装する
○ 簡単なものならシェルスクリプトで実装できる
○ 複数のカスタムアクションを組み合わせることもできる
カスタムアクションの種別

View Slide

8
Versions Maven Plugin を使った依存ライブラリの自動更新のための Composite actions を作った
● HoshinoResort/hr-library-auto-update
● maven コマンドを実行するシェルスクリプトのみで実装
実際の運用では1週間に1回ワークフローをスケジュール実行している
● 依存ライブラリのバージョンチェック処理は時間がかかる
● private リポジトリで運用する場合、
頻繁に実行すると課金の無料枠を浪費してしまう
(余談) Composite actions のサンプル
OSS なので
よかったら
使ってください

View Slide

9
Docker container action
によるカスタムアクション

View Slide

10
ヌーラボ社の Backlog というタスク管理ツールがある
開発のお手伝い先で Backlog を利用しているが、イシューと GitHub の情報を連携する機能がない
● Pull Request を作ったときにリンク情報をイシューのカスタムフィールドに追記したい
● main ブランチにマージしたときにコミット情報をイシューのコメントに追記したい
この2つの機能を実現するためにカスタムアクションを作成した
● kazamori/backlog-github-integration-action
(余談) Java で実装した理由
● ヌーラボ社が公式提供しているライブラリが Java のみだった
○ nulab/backlog4j
Backlog-GitHub integration action
構想: 1ヶ月
実装: 2日

View Slide

11
実際に開発してみた個人的な所感から
● 自分の好きな言語で実装できる
● 実行時に docker pull & docker run で実行される
● GitHub プラットフォーム上のインフラですべて構築できる
Docker container action の特徴
Java で
開発したい！

View Slide

12
Docker container action の振る舞い
すべて
GitHub
インフラ

View Slide

13
Java の CLI アプリケーションと
Docker container action の境界

View Slide

14
Backlog-GitHub integration action は CLI アプリケーションとして実装
● 単体で実行可能
○ gradle run でも実行可能
○ java -jar でも実行可能
○ docker run でも実行可能
● 複数のイベントに対応可能
○ サブコマンドがイベントに対応
○ 要件に応じて拡張しやすい
● GitHub プラットフォームに依存しない
○ 環境変数ではなく CLI パラメーター
○ デバッグや検証の大半をローカルで行う
CLI アプリケーションと設計の狙い
テストや
デバッグ
が容易

View Slide

15
ターミナルからコマンドラインで実行できると安心する
● IDE とか難しくて使いこなせないので、ターミナルとコマンドで操作できると嬉しい
● (私の場合) コードは IDE で書くが、ターミナルで実行する
● ターミナルのシェルで動くならどこでも動かせるはず？
○ ローカルで実行できる
○ Docker コンテナーで実行できる
○ GitHub Actions で実行できる
● 実行コンテキストや環境設定をなるべく減らしたい
単体で実行可能
GitHub Actions
から実行しない
用途でも使える

View Slide

16
GitHub Actions は GitHub のイベントをトリガーに実行される
● CLI のサブコマンドがイベントに対応
● イベントに対する要件に応じて拡張しやすい
○ pull_request イベント
○ push イベント
● 複数イベントを同じカスタムアクションで扱える
○ Backlog のカスタムアクションは他にもあるが、
pull_request イベントと push イベントの両方に
対応するカスタムアクションはない (はず)
○ 複数のカスタムアクションを使いたい理由はない
複数のイベントに対応可能
GitHub Actions で
使えるイベント一覧

View Slide

17
GitHub Actions で使うことを前提としているが、仕様はアプリケーションで決めたい
● CLI パラメーターで明示的に渡さなくても
環境変数を経由してアプリケーション内で読み込むことも可能ではある
● 環境変数に依存してしまうと、テストやデバッグにおいて
必ず GitHub Actions から呼び出さないと検証できない
● CLI アプリケーションが GitHub Actions 専用になってしまう
GitHub プラットフォームに依存しない
デフォルトの
環境変数一覧

View Slide

18
Java アプリケーションと
Docker イメージのビルド

View Slide

19
Java アプリケーション向けに Docker デーモンを使わずに
最適化された Docker/OCI イメージをビルドするためのツール
● GoogleContainerTools/jib
● maven や gradle プラグインから利用できる
目的
● 高速: マルチステージビルドを使ってビルドを最適化して高速
● 再現性: 同じコンテンツから同じイメージを生成
● デーモン要らず: イメージのビルド環境構築を maven/gradle のみで構築
　　　　　　　　依存関係の管理コストが低い
Jib とは

View Slide

20
Jib Gradle プラグイン
jib {
from {
image = 'eclipse-temurin:17-jre-alpine'
platforms {
platform {
architecture = 'amd64'
os = 'linux'
}
}
}
to {
image = 'ghcr.io/kazamori/backlog-github-integration-action'
tags = ['latest']
}
container {
jvmFlags = [
"--add-opens", "java.base/sun.net.www.protocol.https=ALL-UNNAMED",
"--add-opens", "java.base/java.net=ALL-UNNAMED"
]
labels = [
'org.opencontainers.image.description': "GitHub custom action integrates with Nulab's backlog",
'org.opencontainers.image.licenses': 'Apache-2.0',
'org.opencontainers.image.source': 'https://github.com/kazamori/backlog-github-integration-action',
'org.opencontainers.image.title': 'backlog-github-integration-action',
'org.opencontainers.image.url':
'https://github.com/kazamori/backlog-github-integration-action/pkgs/container/backlog-github-integration-action'
]
format = 'OCI'
}
}
jib の設定例

View Slide

21
JVM のビルドイメージは何を使えばいいのか？
Backlog-GitHub integration action は Eclipse Temurin の Docker イメージを使っている
● Eclipse Foundation の Adoptium プロジェクトがビルドした JVM を利用
● 17-jre-alpine のイメージサイズ: 47.52 MiB
信頼できるコミュニティの Docker イメージを使うメリット
● 脆弱性対応の保守への安心感
○ OpenJDK Vulnerability Advisory: 2022/04/19
○ April 2022 Release Status per Platform, Version & Binary Type · Issue #140
Adoptium プロジェクトと Docker イメージ

View Slide

22
カスタムアクションの開発、
テストやデバッグのコツ

View Slide

23
すぐ使えて便利なテクニック
Contexts - GitHub Docs
GitHub Context の dump
steps:
- name: dump github context
run: |
echo "$GITHUB_CONTEXT"
env:
GITHUB_CONTEXT: ${{ toJson(github) }}

View Slide

24
Expressions - GitHub Docs
${{ と }} で囲まれた情報を式として評価できる
● 算術演算や論理演算
● if 文の条件式
○ ワークフローの制御に便利
● 環境変数の設定
○ カスタムアクションの戻り値を後続ステップで参照
● 組み込み関数
○ 一通りみておくと自前で実装しなくて済むかも？
GitHub Actions の Expressions
${{ }}

View Slide

25
複雑な文字列操作をすると、いまどのコンテキストかを把握するのが困難
なるべくシンプルに文字列を扱うのがプラクティスと言える
複数のコンテキストがワークフローファイルに記述される
● yaml 設定の文字列
● GitHub Actions の expressions
● シェル上の文字列
ワークフローにおける複数のコンテキスト
steps:
- name: dump github context
run: |
echo "$GITHUB_CONTEXT"
env:
GITHUB_CONTEXT: ${{ toJson(github) }}
GitHub Actions のオブジェクト
GitHub Actions の expression
シェル上の文字列
JSON 文字列の
エスケープを
やると混乱する

View Slide

26
まとめ

View Slide

27
Java でカスタムアクションを実装するために必要な知識やコツについて説明した
● Docker container action なら Java で実装できる
● GitHub イベントごとに機能実装できると拡張性が高い
○ 設計例の1つとして CLI アプリケーションを紹介
● 逆説的ではあるが、GitHub Actions に依存しないアプリケーションとして実装する
○ テストやデバッグで GitHub Actions を実行するのは労力を要する
● GitHub Actions の Expressions を覚えておこう
○ ワークフロー制御や文字列操作を簡単にできる可能性
まとめ

View Slide

28
GitHub 社のドキュメントや GitHub Actions に関するブログ記事など
● GitHub Actions Documentation
● Creating actions - GitHub Docs
● Supercharging GitHub Actions with Job Summaries
● GitHub Actions: Input types for manual workﬂows
カザモリ社の Backlog-GitHub integration action の紹介記事
● Backlog GitHub integration action
● Commits integrate with Backlog issue
その他、開発中に参考にしたブログ記事など
● GitHub Actions入門 ── ワークフローの基本的な構造からOIDCによる外部サービス認証まで
● GitHub Actions で学ぶシェル芸
● JavaのDockerイメージ何選ぶ？ | フューチャー技術ブログ
リファレンス

View Slide

Custom GitHub Actions by Java

Custom GitHub Actions by Java

kazamori

More Decks by kazamori

Other Decks in Technology

Featured

Transcript