Use verified Node HTTPS with bounded timeouts and separate tool, DNS, TLS and HTTP diagnostics. Cover the preflight with regression tests and document explicit Docker job labels for Runner 3.
14 KiB
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。
実行フロー
- runner の Docker 接続と、公開時の registry secret を検査。
- checkout。Git 認証情報は作業ディレクトリに永続化しない。
- 本体 Dockerfile の
testステージでgo test ./...。 - 3 イメージを順番にビルド。Go や npm のビルド失敗時には公開しない。
- ネットワークなしの一時コンテナで必要な成果物と秘密情報・データの除外、nginx 設定を検査。
- すべてのビルド・検査成功後、3 イメージを registry へ push。
- 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. git.anya.jp を 172.18.0.10 に固定する場合
gitea-runner daemon をホストで動かしている場合、Compose 化は不要。
継続運用では同じコマンドを systemd のサービスとして管理すればよい。
runner のバージョンは Gitea サーバーのバージョンとは別なので、まず
gitea-runner --version と gitea-runner --help で確認する。
名前解決は実行場所ごとに設定する。ホストの /etc/hosts はコンテナへ自動継承されない。
| 通信元 | 必要な設定 |
|---|---|
| ホストで動く 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 |
例として、新規設定が必要なときだけ runner の作業ディレクトリで生成する。
既存 config.yaml を上書きせず、既存の登録ファイル .runner も保持する。
gitea-runner generate-config > config.example.yaml
生成例を参考に、既存設定へ以下をマージする。既存の container.options が
ある場合は値を置き換えず、オプションを追記する。
runner:
capacity: 1
timeout: 2h
container:
options: "--add-host=git.anya.jp:172.18.0.10"
実行中のジョブが終わってから、既存の runner を停止して設定ファイル付きで
起動する。二重起動しないこと。登録時と同じ作業ディレクトリから実行するか、
runner.file に登録ファイルへのパスを指定する。
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の名前解決は直らない。
ホストでの確認:
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等の不足を避けるには、ジョブイメージまで明示する。
# 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:
file: /data/.runner
capacity: 1
timeout: 2h
container:
options: "--add-host=git.anya.jp:172.18.0.10"
docker_host: "unix:///var/run/docker.sock"
# 提示構成で既に存在するネットワークを利用し、自動的な /16 の作成を避ける。
# このネットワークへ参加させるのは信頼済みジョブに限る。
network: "anya-npm-net"
これは共有Docker socketを使用する構成で、強い権限を持つ点は変わらない。
将来は本番サービスと別のCI専用daemon/networkへ分離する。
runnerサービスに既にある extra_hosts とsocketのvolumeは維持する。
ジョブ完了後、Gitea側のComposeディレクトリでrunnerだけを再作成する。
docker compose up -d --no-deps --force-recreate runner
restart だけではCompose環境変数の変更が反映されない。serverサービスや
登録データの削除・再登録は不要。新しいジョブ環境にもDocker CLIがあることと、
docker version でdaemonに接続できることを確認する。
5. 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 の設定と実行成功は、ローカル検証とは別に確認が必要。