181 lines
9.6 KiB
Markdown
181 lines
9.6 KiB
Markdown
# Gitea Actions でのイメージビルド・保管
|
||
|
||
## 対象とフロー
|
||
|
||
`.gitea/workflows/images.yml` は checkout → テスト → ビルド → registry への push を担当する。
|
||
runner の環境構築や Gitea の事前疎通診断は行わず、本番へ自動デプロイもしない。
|
||
導入先は Gitea 1.24.6、対象は `linux/amd64`。
|
||
|
||
| イメージ(prefix: `git.anya.jp/anya/`) | Dockerfile |
|
||
| --- | --- |
|
||
| `pageswiki-app`(app / app2 共通) | `Dockerfile` |
|
||
| `pageswiki-adaptor-gateway` | `Dockerfile.adapter-gateway` |
|
||
| `pageswiki-excalidraw-viewer` | `Dockerfile.excalidraw-viewer` |
|
||
| `pageswiki-gecko-relay`(任意) | `Dockerfile.gecko-relay` |
|
||
|
||
v0.15.0以降はGecko relayを含む4イメージをビルド・昇格します。以下の「3イメージ」は通常配備するapp・gateway・Excalidrawの組を指します。Gecko relayは別overlayで明示的に配備するもので、通常の本番更新では起動しません。
|
||
|
||
Kroki、Mermaid、code-server は upstream の配布イメージを使用する。
|
||
`main` / `mk_district` への push、手動実行でビルド・公開する。
|
||
`v*` タグは別の `release.yml` でビルド済みイメージを昇格し、再ビルドしない。
|
||
採番は [SemVer 2.0.0 の運用規則](versioning.md) に従う。
|
||
本体の `test` ステージで `go test ./...` を実行し、3 イメージのビルドが成功した後に push する。
|
||
3 回の push は原子的ではないため、**ワークフロー全体の成功を確認してから利用**する。
|
||
最後に当該ジョブのローカル CI タグと専用 builder を後処理する。
|
||
|
||
## runner 環境(初回・環境変更時のみ)
|
||
|
||
`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 の構成
|
||
|
||
ホストの Docker ソケットを利用する場合は **`docker.io/gitea/runner:3`(通常版)** を使う。
|
||
`3-dind` / `3-dind-rootless` とソケットの bind mount を混在させない。
|
||
runner が利用する daemon と `anya-npm-net` が存在する daemon は一致させる。
|
||
別 daemon に同名ネットワークを作っても接続は共有されない。
|
||
|
||
Gitea 側 Compose のラベルで Docker 実行方式を明示する。
|
||
workflow の `container.image` が実際のジョブ用イメージを指定する。
|
||
|
||
```yaml
|
||
# 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` は消さない。
|
||
環境変数のラベルは設定ファイルより優先する。
|
||
|
||
```yaml
|
||
runner:
|
||
file: /data/.runner
|
||
capacity: 1
|
||
timeout: 2h
|
||
container:
|
||
docker_host: "unix:///var/run/docker.sock"
|
||
options: "--add-host=git.anya.jp:172.18.0.10"
|
||
# 既存ネットワークを使い、自動的な /16 の作成を避ける。
|
||
network: "anya-npm-net"
|
||
```
|
||
|
||
既存の 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 だけでは環境変数変更は反映されない。登録し直す必要はない。
|
||
PagesWiki 側の Compose を変更しても runner の設定には反映されない。
|
||
Gitea 1.24 では workflow の concurrency / timeout-minutes に依存せず、
|
||
runner の capacity / timeout で制御する。同じ daemon 上の当該ビルドは直列実行し、
|
||
重複ジョブのタグ後処理が衝突しないようにする。BuildKit 内部の並列度は 2。
|
||
|
||
### 名前解決の境界
|
||
|
||
| 通信元 | 名前解決の設定 |
|
||
| --- | --- |
|
||
| 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 権限を持つアクセストークン |
|
||
|
||
runner 登録トークンとは別物。リポジトリ、Dockerfile、build args、チャットへ値を載せない。
|
||
Gitea 1.24 の自動ジョブトークンによるパッケージ公開は前提にしない。
|
||
|
||
任意の Repository Actions Variables:
|
||
|
||
| Variable | 既定値 |
|
||
| --- | --- |
|
||
| IMAGE_REGISTRY | git.anya.jp(スキームなし) |
|
||
| IMAGE_OWNER | anya(小文字) |
|
||
| IMAGE_RUNNER_LABEL | ubuntu-latest |
|
||
|
||
アプリイメージにはソースコードが含まれるため、パッケージの公開範囲にも注意する。
|
||
|
||
## テスト用一時領域
|
||
|
||
Dockerfileのtest段階では、全Goテストを`-p 1`でパッケージ単位に直列化する。
|
||
テスト用`TMPDIR`は最大2GiBのtmpfsとし、SQLiteの一時DBをrunnerのoverlay filesystemから分離する。
|
||
コンパイラ用`GOTMPDIR`はディスク側の`/tmp`に残す。tmpfsは当該RUNの間だけ存在し、
|
||
runtime段階や本番の保存先・WAL・接続タイムアウトには影響しない。
|
||
|
||
CI run 54では、直列化後も既存の壁紙・Ordoschnellic・Seheweitのテストが
|
||
SQLite接続初期化の5秒タイムアウトで失敗した。ストレージ競合を避ける措置であり、
|
||
テスト除外・再試行による成功扱い・本番の期限緩和は行わない。
|
||
tmpfsは最大2GiBのメモリを消費し得るため、runnerにはコンパイラ等と合わせた余裕が必要。
|
||
実ファイル保存の移行確認は、CIとは別に本番DBの隔離コピーで行う。
|
||
|
||
## タグ・容量・本番利用
|
||
|
||
3 イメージ共通で `sha-<40桁のコミットID>` を使用し、自動 latest は付けない。
|
||
同じコミットの再実行は同じタグを再公開し得る。依存取得元まで完全固定ではないため、
|
||
バイト単位の固定には registry の digest を利用する。
|
||
公式 Action はコミット SHA 固定。Gitea にない GitHub artifact API への依存を避けるため、
|
||
Docker Action の build record upload / summary は無効化する。
|
||
|
||
ビルド中は専用 BuildKit builder のキャッシュを共有し、永続 registry cache は未導入。
|
||
容量・保持世代は別途管理し、本番使用中とロールバック対象は削除しない。
|
||
workflow から daemon 全体の docker system prune は行わない。
|
||
|
||
本番利用は手動。既存 Compose はローカルビルド方式のまま維持し、
|
||
registry 利用時だけ overlay を重ねる。
|
||
|
||
```bash
|
||
# 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 \
|
||
pull app app2 adaptor-gateway excalidraw-viewer
|
||
|
||
# バックアップと設定・データの互換性を確認した後に実行する。
|
||
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 等のデプロイ設定も必要。ロールバック時もデータ互換性を確認する。
|
||
|
||
## 公式参照
|
||
|
||
- [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/)
|
||
- [Docker コンテナの DNS と hosts](https://docs.docker.com/engine/network/#dns-services)
|
||
- [Dockerfileの一時tmpfsマウント](https://docs.docker.com/reference/dockerfile/#run---mounttype-tmpfs)
|