Files
pages/docs/operations/gitea-images.md
T
Anya Tokugawa 02883e404b
Test and publish container images / images (push) Failing after 0s
Add Gitea Actions image build and registry publication
Test Go packages in Docker, build and inspect three application images, then publish commit-specific tags. Document dedicated runner and package credentials, and provide an opt-in registry Compose overlay without automatic deployment.
2026-09-27 15:00:42 +09:00

149 lines
8.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Gitea Actions でのイメージビルド・保管
## 対象と境界
`git.anya.jp` は導入時点で Gitea **1.24.6**。ワークフローは
`.gitea/workflows/images.yml`。本番への自動デプロイはしない。
| イメージ | 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. Registry 認証
Repository Settings → Actions → Secrets に次の値を設定する。
| Secret | 内容 |
| --- | --- |
| `REGISTRY_USERNAME` | `anya` 名前空間へ書き込める Gitea アカウント |
| `REGISTRY_TOKEN` | そのアカウントの `write:package` 権限を持つアクセストークン |
runner 登録トークン、Git clone 用の資格情報、PagesWiki のキャンパストークンとは
別物。値をリポジトリ、Dockerfile、build args、チャットへ貼り付けない。
可能ならパッケージ公開用の専用アカウントと最小権限を使う。
Gitea 1.24 のジョブ用自動トークンによるパッケージ公開は前提にしない。
公開先を変える場合の Repository Actions Variables:
| Variable | 既定値 |
| --- | --- |
| `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 を利用**する。
ビルド中のキャッシュは専用 BuildKit builder 内で共有し、永続 registry cache は
初期導入では作らない。runner のキャッシュや registry 世代は容量監視対象とし、
将来の保持期間・GC 設定は本番で使用中の digest とロールバック対象を除外して決める。
ワークフローから daemon 全体の `docker system prune` は実行しない。
公式 Action はバージョン名だけでなく完全なコミット SHA に固定。
Gitea にない GitHub artifact API 依存を避けるため、Docker Action の
build record upload / summary は無効化している。
## 本番でビルドせず利用する(手動)
既存 `docker-compose.yml` はローカルビルド方式のまま保持する。
registry イメージ利用時のみ `docker-compose.registry.yml` を重ねる。
```bash
# パスワード/PATはプロンプトで入力(自動化では --password-stdin を使用)
docker login git.anya.jp
# ワークフロー全体が成功した実際のコミットを指定する。
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` のキャンパス参加トークンなど、既存のデプロイ設定も引き続き必要。
ロールバック時もデータ互換性を確認して以前のタグ/digestを明示する。
ここに記載した本番更新操作はCIからは実行しない。
## 公式参照
導入時のローカル検証(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 1.24 Actions の互換性・制限](https://docs.gitea.com/1.24/usage/actions/comparison/)
- [Gitea Container Registry](https://docs.gitea.com/usage/packages/container/)