Simplify image CI and pin the job runtime
Build and publish container images / images (push) Successful in 11m4s

This commit is contained in:
Anya Tokugawa committed 2026-09-27 18:11:44 +09:00
1 parent d8bfae99a7
commit 2893685aef
3 files changed
+121 -423

No files matched your search

+92 -200
View File
@@ -1,159 +1,53 @@
# Gitea Actions でのイメージビルド・保管
## 対象と境界
## 対象とフロー
`git.anya.jp` は導入時点で Gitea **1.24.6**。ワークフローは
`.gitea/workflows/images.yml`。本番への自動デプロイはしない。
`.gitea/workflows/images.yml` は checkout → テスト → ビルド → registry への push を担当する。
runner の環境構築や Gitea の事前疎通診断は行わず、本番へ自動デプロイもしない。
導入先は Gitea 1.24.6、対象は `linux/amd64`。
| イメージ | Dockerfile | 利用先 |
| --- | --- | --- |
| `git.anya.jp/anya/pageswiki-app` | `Dockerfile` | app / app2 共通 |
| `git.anya.jp/anya/pageswiki-adaptor-gateway` | `Dockerfile.adapter-gateway` | code-server / vim.wasm 連携 |
| `git.anya.jp/anya/pageswiki-excalidraw-viewer` | `Dockerfile.excalidraw-viewer` | Excalidraw Viewer |
Kroki、Mermaid、code-server は upstream の配布イメージを利用するため、
このワークフローで再ビルド・再配布しない。現在の対象は `linux/amd64`。
## 実行フロー
1. runner の Docker 接続と、公開時の registry secret を検査。
2. checkout。Git 認証情報は作業ディレクトリに永続化しない。
3. 本体 Dockerfile の `test` ステージで `go test ./...`。
4. 3 イメージを順番にビルド。Go や npm のビルド失敗時には公開しない。
5. ネットワークなしの一時コンテナで必要な成果物と秘密情報・データの除外、nginx 設定を検査。
6. すべてのビルド・検査成功後、3 イメージを registry へ push。
7. runner にロードした当該 CI タグを削除し、Buildx Action が専用 builder を後処理。
registry への 3 回の push は原子的ではない。途中で通信・認証・容量エラーが
起きた場合は一部のみ存在し得るため、**必ずワークフロー全体の成功を確認してから利用**する。
ビルド検証のみの手動実行では push を省略し、registry secret は不要。
## Gitea 側の設定
### 1. リポジトリの Actions を有効化
リポジトリ設定で Actions を有効にする。
- リポジトリ: <https://git.anya.jp/anya/wikipages>
- 実行履歴: <https://git.anya.jp/anya/wikipages/actions>
`main` / `mk_district` への push、`v*` タグの push が対象。
`workflow_dispatch` による手動実行も定義している。Gitea の手動実行 UI に
ワークフローが出ない場合は、デフォルトブランチにワークフローを取り込む必要がある。
本設定を追加しただけでは main へのマージは実施しない。
### 2. 専用 runner
runner の実行環境には以下が必要。
- Linux amd64、bash、git、Docker CLI と利用可能な Docker daemon。
- Node.js 20 対応の JavaScript Action 実行環境。
- Gitea、GitHub、Docker Hub、Go module proxy、npm registry への疎通。
- 3 イメージとビルドキャッシュを扱えるディスク容量。
既定のジョブラベルは `ubuntu-latest`。通常の同名ラベルでも、実体が Node.js
のみのコンテナでは Docker CLI や daemon が利用できるとは限らない。
**ジョブ環境内で `docker version` が成功するように構成すること。**
別ラベルの場合は Repository Actions Variable `IMAGE_RUNNER_LABEL` に設定する。
例: 専用 host runner を `pageswiki-image-builder:host` で登録し、変数には
`pageswiki-image-builder` を指定する。既存 runner へ無条件に host ラベルを追加しない。
Docker socket を使えるジョブは daemon の強い権限を持つ。本番サーバーと共用せず、
信頼するコードのみを実行する専用 runner / daemon を利用する。外部 fork の PR
をこの runner で実行しない。本ワークフローは意図的に PR トリガーを設けていない。
Gitea 1.24 では workflow の `concurrency`、`permissions`、job の
`timeout-minutes` に依存できない。runner 側で **capacity=1** と適切な timeout
(目安 2 時間)を設定する。同じコミットの重複実行でも、ロードした CI タグの
後処理が別ジョブと衝突しないよう、レポジトリ用 runner は同一 daemon で直列実行する。
BuildKit の内部並列度も 2 に制限しているが、これはCPU・メモリの厳密な上限ではない。
### 3. git.anya.jp を 172.18.0.10 に固定する場合
`gitea-runner daemon` をホストで動かしている場合、Compose 化は不要。
継続運用では同じコマンドを systemd のサービスとして管理すればよい。
runner のバージョンは Gitea サーバーのバージョンとは別なので、まず
`gitea-runner --version` と `gitea-runner --help` で確認する。
名前解決は実行場所ごとに設定する。ホストの `/etc/hosts` はコンテナへ自動継承されない。
| 通信元 | 必要な設定 |
| イメージ(prefix: `git.anya.jp/anya/`) | Dockerfile |
| --- | --- |
| ホストで動く runner 本体 | ホストのDNS、または `/etc/hosts` に `172.18.0.10 git.anya.jp` |
| runner が起動するジョブコンテナ | runner 設定の `container.options` に `--add-host=git.anya.jp:172.18.0.10` |
| `docker push` を実行する Docker daemon | daemon が動くホストのDNS/hosts。DinDならdaemonコンテナ自身の `extra_hosts` |
| `pageswiki-app`(app / app2 共通) | `Dockerfile` |
| `pageswiki-adaptor-gateway` | `Dockerfile.adapter-gateway` |
| `pageswiki-excalidraw-viewer` | `Dockerfile.excalidraw-viewer` |
例として、新規設定が必要なときだけ runner の作業ディレクトリで生成する。
既存 `config.yaml` を上書きせず、既存の登録ファイル `.runner` も保持する。
Kroki、Mermaid、code-server は upstream の配布イメージを使用する。
`main` / `mk_district` への push、`v*` タグ、手動実行でビルド・公開する。
本体の `test` ステージで `go test ./...` を実行し、3 イメージのビルドが成功した後に push する。
3 回の push は原子的ではないため、**ワークフロー全体の成功を確認してから利用**する。
最後に当該ジョブのローカル CI タグと専用 builder を後処理する。
```bash
gitea-runner generate-config > config.example.yaml
```
## runner 環境(初回・環境変更時のみ)
生成例を参考に、既存設定へ以下をマージする。既存の `container.options` が
ある場合は値を置き換えず、オプションを追記する。
`ubuntu-latest` は runner を選ぶラベルであり、ツールの存在を保証するものではない。
workflow の `container.image` で Gitea 公式ジョブイメージを digest 固定する。
その中の Node.js、git、bash、Docker CLI を使い、毎回のインストールや探索は行わない。
Node は tool cache 内にあるため、workflow の `PATH` に明示する。
**ジョブイメージの更新時には Node のパスも併せて確認・更新する。**
2026-09-27 にローカル実行で確認した組み合わせ:
- イメージ: `docker.gitea.com/runner-images:ubuntu-latest@sha256:fd911d7417bfbf0f454530e447da95b58001e1df41bbc5e1a8dd35d432575aae`
- Node: `/opt/acttoolcache/node/24.19.0/x64/bin/node`
Docker daemon、外部ソース・パッケージ取得先への接続、ビルド用ディスク容量は必要。
Docker socket を使うジョブは強い権限を持つため、信頼するコードのみを実行する。
外部 PR はトリガーにしていない。将来は本番と別の CI 専用 daemon へ分離する。
### 提示された Docker 版 Runner 3 の構成
Gitea 側 Compose のラベルで Docker 実行方式を明示する。
workflow の `container.image` が実際のジョブ用イメージを指定する。
```yaml
runner:
capacity: 1
timeout: 2h
container:
options: "--add-host=git.anya.jp:172.18.0.10"
```
実行中のジョブが終わってから、既存の runner を停止して設定ファイル付きで
起動する。二重起動しないこと。登録時と同じ作業ディレクトリから実行するか、
`runner.file` に登録ファイルへのパスを指定する。
```bash
gitea-runner --config /absolute/path/to/config.yaml daemon
```
`container.options` は Docker ジョブにのみ作用し、host ラベルのジョブには不要。
runner 自体をDockerコンテナ化する場合は、そのComposeサービスにも別途
`extra_hosts: ["git.anya.jp:172.18.0.10"]` を追加する。
**PagesWikiアプリ側の `docker-compose.yml` に追加してもCIの名前解決は直らない。**
ホストでの確認:
```bash
getent ahostsv4 git.anya.jp
curl --fail --connect-timeout 5 --max-time 15 https://git.anya.jp/api/v1/version
```
workflowにもcheckoutより前のHTTPS疎通チェックを置いている。これはJavaScript
Actionでも必要なNode.jsの標準HTTPSモジュールを使うため、ジョブ環境にcurlを
追加する必要はない。Node.js自体がない場合はツール不足として明示し、DNS・TLS・
タイムアウト・HTTPエラーと区別する。TLS検証は有効、応答待ちは15秒で打ち切る。
上のcurlコマンドはホストでの手動確認例。
ただしrunner自体が
Giteaへ接続できなければジョブは取得できないため、このチェックも実行されない。
Waitingのままならrunnerのオンライン状態・ラベル・空きスロットも確認する。
URLは `https://git.anya.jp` のまま保ち、IPのURLへの変更やTLS検証無効化はしない。
また `172.18.0.10` と競合するDockerネットワークを作らないこと。特に
`172.18.0.0/16` のようなネットワークで宛先を吸い込む問題はhosts設定では直らない。
ネットワークが必要なら、実ネットワークと非重複のアドレス帯から `/27` 等を選ぶ。
この変更で既存ネットワークの作成・変更は実施しない。
2026-09-27の確認では、作業ホストと `--add-host` 付き一時コンテナの両方から
指定IPのGiteaへTLS検証付きで接続できた。実際のrunnerの設定変更・再起動は未実施。
### 4. Docker版 Runner 3 の提示構成について
`docker.io/gitea/runner:3` を利用する場合、環境変数
`GITEA_RUNNER_LABELS: "ubuntu-latest"` はUbuntuコンテナを指定するものではない。
実行方式の省略はhostモードなので、runnerコンテナ自身の中でジョブを実行する。
curl等の不足を避けるには、ジョブイメージまで明示する。
```yaml
# Gitea側 docker-compose.yml の runner.environment を変更
# Gitea 側 docker-compose.yml の runner.environment
GITEA_RUNNER_LABELS: "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
```
`./runner/data:/data` と `./runner/config.yaml:/config.yaml` の配置なら、
`runner/config.yaml` の該当箇所へ以下をマージする。登録済みの `.runner` は消さない。
環境変数のラベルは `runner.labels` より優先するため、Compose側も変更する。
既存の `runner/config.yaml` へ以下をマージする。`.runner` は消さない。
環境変数のラベルは設定ファイルより優先する。
```yaml
runner:
@@ -161,78 +55,85 @@ runner:
capacity: 1
timeout: 2h
container:
options: "--add-host=git.anya.jp:172.18.0.10"
docker_host: "unix:///var/run/docker.sock"
# 提示構成で既に存在するネットワークを利用し、自動的な /16 の作成を避ける。
# このネットワークへ参加させるのは信頼済みジョブに限る。
options: "--add-host=git.anya.jp:172.18.0.10"
# 既存ネットワークを使い、自動的な /16 の作成を避ける。
network: "anya-npm-net"
```
これは共有Docker socketを使用する構成で、強い権限を持つ点は変わらない。
将来は本番サービスと別のCI専用daemon/networkへ分離する。
runnerサービスに既にある `extra_hosts` とsocketのvolumeは維持する。
ジョブ完了後、Gitea側のComposeディレクトリでrunnerだけを再作成する。
既存の options があれば追記する。runner サービスの socket volume と
`extra_hosts: ["git.anya.jp:172.18.0.10"]` は維持する。
実行中ジョブの完了後、Gitea 側 Compose ディレクトリで反映する。
```bash
docker compose up -d --no-deps --force-recreate runner
```
`restart` だけではCompose環境変数の変更が反映されない。serverサービスや
登録データの削除・再登録は不要。新しいジョブ環境にもDocker CLIがあることと、
`docker version` でdaemonに接続できることを確認する。
restart だけでは環境変数変更は反映されない。登録し直す必要はない。
PagesWiki 側の Compose を変更しても runner の設定には反映されない。
Gitea 1.24 では workflow の concurrency / timeout-minutes に依存せず、
runner の capacity / timeout で制御する。同じ daemon 上の当該ビルドは直列実行し、
重複ジョブのタグ後処理が衝突しないようにする。BuildKit 内部の並列度は 2。
### 5. Registry 認証
### 名前解決の境界
Repository Settings → Actions → Secrets に次の値を設定する。
| 通信元 | 名前解決の設定 |
| --- | --- |
| runner コンテナ | runner サービスの extra_hosts |
| ジョブコンテナ | container.options の --add-host |
| docker push を行う daemon | daemon ホストの DNS / hosts(DinD なら daemon コンテナ自身) |
hosts はコンテナ間で自動継承されない。push は Docker daemon で行うため、
BuildKit には registry 用 hosts の追加は不要。
URL は HTTPS のホスト名を維持し、TLS 検証は無効化しない。
重複ネットワークを作らず、新設時は非重複の /27 等を選ぶ。
疎通診断は問題発生時に運用者が行い、通常のビルドには組み込まない。
## Gitea リポジトリ設定
[リポジトリ](https://git.anya.jp/anya/wikipages)で Actions を有効化し、
[実行履歴](https://git.anya.jp/anya/wikipages/actions)で結果を確認する。
Repository Settings → Actions → Secrets:
| Secret | 内容 |
| --- | --- |
| `REGISTRY_USERNAME` | `anya` 名前空間へ書き込める Gitea アカウント |
| `REGISTRY_TOKEN` | そのアカウントの `write:package` 権限を持つアクセストークン |
| REGISTRY_USERNAME | anya 名前空間へ書き込める Gitea アカウント |
| REGISTRY_TOKEN | そのアカウントの write:package 権限を持つアクセストークン |
runner 登録トークン、Git clone 用の資格情報、PagesWiki のキャンパストークンとは
別物。値をリポジトリ、Dockerfile、build args、チャットへ貼り付けない。
可能ならパッケージ公開用の専用アカウントと最小権限を使う。
Gitea 1.24 のジョブ用自動トークンによるパッケージ公開は前提にしない。
runner 登録トークンとは別物。リポジトリ、Dockerfile、build args、チャットへ値を載せない。
Gitea 1.24 の自動ジョブトークンによるパッケージ公開は前提にしない。
公開先を変える場合の Repository Actions Variables:
任意の Repository Actions Variables:
| Variable | 既定値 |
| --- | --- |
| `IMAGE_REGISTRY` | `git.anya.jp`(スキームなし) |
| `IMAGE_OWNER` | `anya`(小文字) |
| `IMAGE_RUNNER_LABEL` | `ubuntu-latest` |
| IMAGE_REGISTRY | git.anya.jp(スキームなし) |
| IMAGE_OWNER | anya(小文字) |
| IMAGE_RUNNER_LABEL | ubuntu-latest |
パッケージの公開・非公開設定は Gitea 側で確認する。アプリイメージには
ソースコードが含まれるため、ソースを非公開運用する場合はパッケージも同様に扱う。
アプリイメージにはソースコードが含まれるため、パッケージの公開範囲にも注意する。
## タグ・キャッシュ・容量
## タグ・容量・本番利用
3 イメージすべて同じ `sha-<40桁のコミットID>` タグを使う。
自動 `latest` / ブランチ別の可変タグは付けないため、古いジョブが後から完了しても
新しいリリースを上書きしない。同一コミットの再実行は同じ SHA タグを再公開し得る。
base image と npm / apk 等の取得元は完全固定ではないため、**バイト単位で同一の
イメージを指定する必要があるときは registry の digest を利用**する。
3 イメージ共通で `sha-<40桁のコミットID>` を使用し、自動 latest は付けない。
同じコミットの再実行は同じタグを再公開し得る。依存取得元まで完全固定ではないため、
バイト単位の固定には registry の digest を利用する。
公式 Action はコミット SHA 固定。Gitea にない GitHub artifact API への依存を避けるため、
Docker Action の build record upload / summary は無効化する。
ビルド中のキャッシュは専用 BuildKit builder 内で共有し、永続 registry cache は
初期導入では作らない。runner のキャッシュや registry 世代は容量監視対象とし、
将来の保持期間・GC 設定は本番で使用中の digest とロールバック対象を除外して決める。
ワークフローから daemon 全体の `docker system prune` は実行しない。
ビルド中は専用 BuildKit builder のキャッシュを共有し、永続 registry cache は未導入。
容量・保持世代は別途管理し、本番使用中とロールバック対象は削除しない。
workflow から daemon 全体の docker system prune は行わない。
公式 Action はバージョン名だけでなく完全なコミット SHA に固定。
Gitea にない GitHub artifact API 依存を避けるため、Docker Action の
build record upload / summary は無効化している。
## 本番でビルドせず利用する(手動)
既存 `docker-compose.yml` はローカルビルド方式のまま保持する。
registry イメージ利用時のみ `docker-compose.registry.yml` を重ねる。
本番利用は手動。既存 Compose はローカルビルド方式のまま維持し、
registry 利用時だけ overlay を重ねる。
```bash
# パスワード/PATはプロンプトで入力(自動化では --password-stdin を使用)
# PAT はプロンプトで入力(自動化では --password-stdin)。
docker login git.anya.jp
# ワークフロー全体が成功した実際のコミットを指定する。
# 全ステップが成功した実際のコミット ID に置き換える。
export PAGESWIKI_IMAGE_TAG='sha-<40桁のコミットID>'
docker compose -f docker-compose.yml -f docker-compose.registry.yml \
@@ -243,22 +144,13 @@ docker compose -f docker-compose.yml -f docker-compose.registry.yml \
up -d --no-build app app2 adaptor-gateway excalidraw-viewer
```
上記タグは例示のプレースホルダー。実コマンドでは実際のタグへ置換する。
prefix を変える場合は `PAGESWIKI_IMAGE_PREFIX`(既定 `git.anya.jp/anya`)。
`.env` のキャンパス参加トークンなど、既存のデプロイ設定も引き続き必要。
ロールバック時もデータ互換性を確認して以前のタグ/digestを明示する。
ここに記載した本番更新操作はCIからは実行しない。
prefix の変更は `PAGESWIKI_IMAGE_PREFIX`(既定 git.anya.jp/anya)。
既存 .env 等のデプロイ設定も必要。ロールバック時もデータ互換性を確認する。
## 公式参照
導入時のローカル検証(2026-09-27): Docker test ステージの全 Go テスト、
3 Dockerfile の実ビルド、成果物/秘密情報除外検査、registry Compose の解決を確認。
actionlint は Gitea 固有の絶対 Action URL を検証入力でのみ通常形式に置換して成功。
Gitea 上の runner / secrets の設定と実行成功は、ローカル検証とは別に確認が必要。
- [Gitea 1.24 Act Runner](https://docs.gitea.com/1.24/usage/actions/act-runner/)
- [Gitea Runner のラベル](https://docs.gitea.com/runner/labels/)
- [Gitea Runner の設定](https://docs.gitea.com/runner/configuration/)
- [Gitea 1.24 Actions の互換性・制限](https://docs.gitea.com/1.24/usage/actions/comparison/)
- [Gitea Container Registry](https://docs.gitea.com/usage/packages/container/)
- [Gitea Runner設定(runner自身のバージョンに合わせて参照)](https://docs.gitea.com/runner/2/configuration/)
- [Gitea Runner 3 のラベルと優先順位](https://docs.gitea.com/runner/labels/)
- [DockerコンテナのDNSとhosts](https://docs.docker.com/engine/network/#dns-services)
- [Docker コンテナの DNS と hosts](https://docs.docker.com/engine/network/#dns-services)