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

8.3 KiB
Raw Blame History

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 を有効にする。

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 を重ねる。

# パスワード/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 の設定と実行成功は、ローカル検証とは別に確認が必要。