6 Commits
Author SHA1 Message Date
Anya Tokugawa b312a50d37 Adopt SemVer 2.0.0 and promote release images by digest
Build and publish container images / images (push) Successful in 10m38s
Release container images / release (push) Successful in 24s
2026-09-27 19:52:58 +09:00
Anya Tokugawa 2893685aef Simplify image CI and pin the job runtime
Build and publish container images / images (push) Successful in 11m4s
2026-09-27 18:11:44 +09:00
Anya Tokugawa d8bfae99a7 Remove curl dependency from CI connectivity checks
Test and publish container images / images (push) Failing after 1s
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.
2026-09-27 17:50:15 +09:00
Anya Tokugawa c3bea8a3b7 Document runner host mapping and check Gitea connectivity
Test and publish container images / images (push) Failing after 0s
2026-09-27 17:34:35 +09:00
Anya Tokugawa 02883e404b Add Gitea Actions image build and registry publication
Test and publish container images / images (push) Failing after 0s
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
anya 68f7d7a571 Merge pull request 'merge mk_district' (#2) from mk_district into main
Reviewed-on: anya/wikipages#2
2026-09-27 14:49:50 +09:00
9 changed files with 646 additions and 1 deletions

No files matched your search

+113
View File
@@ -0,0 +1,113 @@
name: Build and publish container images
on:
push:
branches: [main, mk_district]
workflow_dispatch:
jobs:
images:
runs-on: ${{ vars.IMAGE_RUNNER_LABEL || 'ubuntu-latest' }}
# Verified linux/amd64 job tools. The runner label only selects a runner.
container:
image: docker.gitea.com/runner-images:ubuntu-latest@sha256:fd911d7417bfbf0f454530e447da95b58001e1df41bbc5e1a8dd35d432575aae
env:
REGISTRY: ${{ vars.IMAGE_REGISTRY || 'git.anya.jp' }}
IMAGE_OWNER: ${{ vars.IMAGE_OWNER || 'anya' }}
IMAGE_TAG: sha-${{ github.sha }}
# The pinned image stores Node in its tool cache. Make it available to
# both shell steps and JavaScript Actions without login-shell setup.
PATH: /opt/acttoolcache/node/24.19.0/x64/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
DOCKER_BUILD_SUMMARY: 'false'
DOCKER_BUILD_RECORD_UPLOAD: 'false'
steps:
- name: Checkout
uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
ref: ${{ github.sha }}
persist-credentials: false
- name: Set up Buildx
uses: https://github.com/docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
with:
version: v0.34.0
buildkitd-config-inline: |
[worker.oci]
max-parallelism = 2
- name: Test release tooling
run: node --test tools/ci/release-images.test.mjs
- name: Test
uses: https://github.com/docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
with:
context: .
file: Dockerfile
target: test
platforms: linux/amd64
push: false
- name: Log in to registry
uses: https://github.com/docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
with:
registry: ${{ env.REGISTRY }}
username: ${{ secrets.REGISTRY_USERNAME }}
password: ${{ secrets.REGISTRY_TOKEN }}
- name: Build PagesWiki
uses: https://github.com/docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
with:
context: .
file: Dockerfile
target: runtime
platforms: linux/amd64
load: true
tags: ${{ env.REGISTRY }}/${{ env.IMAGE_OWNER }}/pageswiki-app:${{ env.IMAGE_TAG }}
labels: |
org.opencontainers.image.revision=${{ github.sha }}
org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
- name: Build adaptor gateway
uses: https://github.com/docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
with:
context: .
file: Dockerfile.adapter-gateway
platforms: linux/amd64
load: true
tags: ${{ env.REGISTRY }}/${{ env.IMAGE_OWNER }}/pageswiki-adaptor-gateway:${{ env.IMAGE_TAG }}
labels: |
org.opencontainers.image.revision=${{ github.sha }}
org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
- name: Build Excalidraw viewer
uses: https://github.com/docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
with:
context: .
file: Dockerfile.excalidraw-viewer
platforms: linux/amd64
load: true
tags: ${{ env.REGISTRY }}/${{ env.IMAGE_OWNER }}/pageswiki-excalidraw-viewer:${{ env.IMAGE_TAG }}
labels: |
org.opencontainers.image.revision=${{ github.sha }}
org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
# Publish only after all builds succeed. Use the host daemon for registry
# access; BuildKit does not inherit the runner's /etc/hosts entries.
- name: Push images
shell: bash
run: |
set -euo pipefail
for image in pageswiki-app pageswiki-adaptor-gateway pageswiki-excalidraw-viewer; do
docker push "$REGISTRY/$IMAGE_OWNER/$image:$IMAGE_TAG"
done
- name: Remove local CI image tags
if: always()
shell: bash
run: |
for image in pageswiki-app pageswiki-adaptor-gateway pageswiki-excalidraw-viewer; do
ref="$REGISTRY/$IMAGE_OWNER/$image:$IMAGE_TAG"
if docker image inspect "$ref" >/dev/null 2>&1; then
docker image rm "$ref" || echo "Could not remove local CI tag: $ref" >&2
fi
done
+46
View File
@@ -0,0 +1,46 @@
name: Release container images
on:
push:
tags: ['v*']
# Retry against the same tag if a registry operation was interrupted.
workflow_dispatch:
jobs:
release:
if: startsWith(github.ref, 'refs/tags/v')
runs-on: ${{ vars.IMAGE_RUNNER_LABEL || 'ubuntu-latest' }}
container:
image: docker.gitea.com/runner-images:ubuntu-latest@sha256:fd911d7417bfbf0f454530e447da95b58001e1df41bbc5e1a8dd35d432575aae
env:
REGISTRY: ${{ vars.IMAGE_REGISTRY || 'git.anya.jp' }}
IMAGE_OWNER: ${{ vars.IMAGE_OWNER || 'anya' }}
RELEASE_REF: ${{ github.ref }}
PATH: /opt/acttoolcache/node/24.19.0/x64/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
DOCKER_BUILD_SUMMARY: 'false'
DOCKER_BUILD_RECORD_UPLOAD: 'false'
steps:
- name: Checkout release tag
uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
ref: ${{ github.ref }}
persist-credentials: false
- name: Validate release version
run: node tools/ci/release-images.mjs --validate
- name: Set up Buildx tools
uses: https://github.com/docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
with:
version: v0.34.0
driver: docker
- name: Log in to registry
uses: https://github.com/docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
with:
registry: ${{ env.REGISTRY }}
username: ${{ secrets.REGISTRY_USERNAME }}
password: ${{ secrets.REGISTRY_TOKEN }}
- name: Promote existing images without rebuilding
run: node tools/ci/release-images.mjs
+5 -1
View File
@@ -1,4 +1,4 @@
FROM golang:1.25-alpine FROM golang:1.25-alpine AS source
WORKDIR /src WORKDIR /src
@@ -10,6 +10,10 @@ RUN go mod download
COPY . . COPY . .
FROM source AS test
RUN go test ./...
FROM source AS runtime
RUN go build -o /pageswiki ./cmd/pageswiki RUN go build -o /pageswiki ./cmd/pageswiki
EXPOSE 8081 EXPOSE 8081
+12
View File
@@ -2,6 +2,18 @@
Simplest and powerful wiki architecture for personal Simplest and powerful wiki architecture for personal
## Container CI
Gitea Actions tests and builds the application, adaptor gateway, and Excalidraw
viewer, then publishes them to the Gitea container registry with commit-SHA tags.
See [Gitea image builds and registry setup](docs/operations/gitea-images.md) for
runner requirements, registry secrets, and the optional registry Compose overlay.
The workflow does not deploy to production.
PagesWiki follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
Release tags (starting with `v0.1.0`) promote existing tested images without
rebuilding. See the [versioning and release policy](docs/operations/versioning.md).
## Knowledge City Model ## Knowledge City Model
Pages Wiki uses urban language for its content hierarchy: Pages Wiki uses urban language for its content hierarchy:
+11
View File
@@ -0,0 +1,11 @@
# Optional overlay. Never builds locally when used with `up --no-build`.
# Use all three images from the same successful workflow, identified by SHA.
services:
app:
image: ${PAGESWIKI_IMAGE_PREFIX:-git.anya.jp/anya}/pageswiki-app:${PAGESWIKI_IMAGE_TAG:?Set the image tag from a successful Gitea workflow}
app2:
image: ${PAGESWIKI_IMAGE_PREFIX:-git.anya.jp/anya}/pageswiki-app:${PAGESWIKI_IMAGE_TAG:?Set the image tag from a successful Gitea workflow}
adaptor-gateway:
image: ${PAGESWIKI_IMAGE_PREFIX:-git.anya.jp/anya}/pageswiki-adaptor-gateway:${PAGESWIKI_IMAGE_TAG:?Set the image tag from a successful Gitea workflow}
excalidraw-viewer:
image: ${PAGESWIKI_IMAGE_PREFIX:-git.anya.jp/anya}/pageswiki-excalidraw-viewer:${PAGESWIKI_IMAGE_TAG:?Set the image tag from a successful Gitea workflow}
+163
View File
@@ -0,0 +1,163 @@
# 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` |
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 |
アプリイメージにはソースコードが含まれるため、パッケージの公開範囲にも注意する。
## タグ・容量・本番利用
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)
+81
View File
@@ -0,0 +1,81 @@
# バージョニングとリリース
PagesWiki は [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) を採用する。
初回リリースは **0.1.0**。Git タグとコンテナタグには接頭辞 `v` を付ける。
`v` は SemVer のバージョン番号そのものには含まれない。
## 互換性の対象
PagesWiki の公開インターフェースとして、設計書・利用手順で公開した次の契約を扱う。
- HTTP API の URI、認証方式、要求・応答形式、および公開 URI の解決規則。
- CalDAV / iCalendar 等の外部クライアントとの連携契約。
- CLI の公開コマンド・オプション、および機械処理向けに明文化した出力形式。
- 文書化した設定キー、環境変数、インポート/エクスポート形式。
- 公開した連携アダプタ・システム拡張のインターフェース。
内部関数、DB の内部テーブル構造、非公開エンドポイント、HTML/CSS の内部構造は
安定 API としない。ただし DB・ファイル正本の移行が必要な場合は必ず移行手順と
バックアップ条件を記載し、ダウングレード可能とは仮定しない。
## 番号の更新
| 変更 | 1.0.0 以降 | 初期開発期間 0.y.z の運用 |
| --- | --- | --- |
| 後方互換な不具合修正 | PATCH を増やす | PATCH を増やす |
| 後方互換な機能追加・公開 API の非推奨化 | MINOR を増やし PATCH を 0 に戻す | MINOR を増やし PATCH を 0 に戻す |
| 公開インターフェースの非互換変更 | MAJOR を増やし MINOR/PATCH を 0 に戻す | MINOR を増やし非互換点・移行方法を明記 |
0.x は SemVer 上の初期開発期間であり、公開 API の安定性はまだ保証しない。
1.0.0 は上記公開契約を安定化させた時点で明示的に採番する。
CI はバージョンを自動で繰り上げない。変更の意味を確認してリリース担当者が選ぶ。
`0.2.0-rc.1` 等のプレリリースを認める。数値識別子の先頭ゼロは禁止する。
ビルドメタデータ `+build.001` は認めるが、バージョンの優先順位には影響しない。
Gitea のコンテナタグは大文字小文字を区別しないため、**配布タグの識別子は小文字に限定**する。
これは配布側の命名制限であり、SemVer 自体では大文字も有効。
## Git とコンテナタグの対応
| Git | コンテナタグ |
| --- | --- |
| 通常の main コミット | `sha-<40桁コミットID>` |
| `v0.1.0` | `v0.1.0` |
| `v0.2.0-rc.1` | `v0.2.0-rc.1` |
| `v0.2.0+build.001` | `v0.2.0_build.001` |
Docker タグには `+` を使えないため `_` へ置換する。SemVer では `_` が使えないので
この変換は衝突しない。コンテナタグの 128 文字制限を超えるリリース名は拒否する。
`latest`、`v0`、`v0.1` 等の可変エイリアスは自動更新しない。
## リリース手順
1. main の Build and publish container images が成功したコミットを選ぶ。
2. 差分・互換性・移行要否を確認し、そのコミットに注釈付き Git タグを付けて push。
3. Release container images が、そのコミットの SHA タグを digest に解決し、
3 イメージの revision ラベルと既存リリースタグを確認して同名タグへ昇格する。
4. ワークフロー全体の成功と、ログに記録された 3 つの digest を確認して利用する。
```bash
# リリース対象のビルド成功済みコミットを明示する。以下は例。
git tag -a v0.1.0 <成功済みコミットID> -m "PagesWiki 0.1.0"
git push origin refs/tags/v0.1.0
```
昇格では再ビルドもレイヤーのダウンロードも行わず、元の manifest digest を維持する。
イメージのラベルを後付けで書き換えることもしない(digest が変わるため)。
元の `org.opencontainers.image.revision` が Git タグのコミットと一致することを確認する。
ソースイメージが欠けていれば停止する。自動でビルドへフォールバックしない。
公開済み Git タグの付け替えや、異なる digest によるリリースタグの上書きを禁止する。
内容を変更する場合は新しいバージョンを発行する。同じ digest の再実行だけは許可する。
3 イメージの更新は原子的ではない。途中失敗時は同じタグのジョブを再実行し、
すでに正しい digest を指しているものはスキップして残りを処理する。
registry の比較・更新は単一トランザクションではないため、リリースは同一 runner で
直列実行し、別クライアントで同じタグを更新しない。管理者は Git の `v*` 保護と
レジストリ側で利用可能なタグ保護も検討する。CI の検査は権限管理の代替ではない。
公開後の SHA タグを再ビルドで更新しても、リリースタグを追従更新してはならない。
本番への自動デプロイはしない。`PAGESWIKI_IMAGE_TAG=v0.1.0` のように指定して
[レジストリ用 Compose](gitea-images.md) を利用する。
+99
View File
@@ -0,0 +1,99 @@
import {spawnSync} from 'node:child_process';
import {pathToFileURL} from 'node:url';
export const images = ['pageswiki-app', 'pageswiki-adaptor-gateway', 'pageswiki-excalidraw-viewer'];
// SemVer 2.0.0: numeric prerelease identifiers cannot have leading zeroes.
const number = '(0|[1-9][0-9]*)';
const identifier = '(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)';
const semver = new RegExp(`^${number}\\.${number}\\.${number}(?:-${identifier}(?:\\.${identifier})*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$`);
export function imageTag(ref) {
if (!ref.startsWith('refs/tags/v')) throw new Error('Release must run on a refs/tags/v… Git tag');
const tag = ref.slice('refs/tags/'.length);
if (!semver.test(tag.slice(1)) || /\s/.test(tag)) throw new Error(`Invalid SemVer 2.0.0 tag: ${tag}`);
// Gitea stores container tags case-insensitively; reject instead of silently
// collapsing distinct SemVer identifiers. '+' is not a Docker tag character.
if (/[A-Z]/.test(tag)) throw new Error('Release identifiers must be lowercase for the Gitea registry');
const result = tag.replace('+', '_');
if (result.length > 128) throw new Error('Container release tag exceeds 128 characters');
return result;
}
function run(command, args) {
const result = spawnSync(command, args, {encoding: 'utf8', timeout: 120000, maxBuffer: 4 * 1024 * 1024});
if (result.error) throw result.error;
if (result.status !== 0) throw new Error(`${command} failed: ${result.stderr.trim()}`);
return result.stdout.trim();
}
export function dockerClient(execute = run) {
function inspect(ref, field, optional = false) {
try {
return JSON.parse(execute('docker', ['buildx', 'imagetools', 'inspect', '--format', `{{json .${field}}}`, ref]));
} catch (error) {
// Only an explicit missing manifest is absence, never auth/TLS/timeouts.
if (optional && (error.message.endsWith(`ERROR: ${ref}: not found`) || /\bmanifest unknown\b/i.test(error.message))) return null;
throw error;
}
}
return {
digest(ref, optional = false) {
const manifest = inspect(ref, 'Manifest', optional);
if (manifest === null) return null;
if (!/^sha256:[0-9a-f]{64}$/.test(manifest.digest)) throw new Error(`Invalid registry digest: ${ref}`);
return manifest.digest;
},
revision(ref) {
const config = inspect(ref, 'Image');
if (config.os !== 'linux' || config.architecture !== 'amd64') throw new Error(`Expected linux/amd64 source: ${ref}`);
return config.config?.Labels?.['org.opencontainers.image.revision'];
},
copy(source, destination) {
execute('docker', ['buildx', 'imagetools', 'create', '--prefer-index=false', '--tag', destination, source]);
},
};
}
export function promote({ref, revision, prefix}, client = dockerClient(), log = console.log) {
const tag = imageTag(ref);
if (!/^[0-9a-f]{40}$/.test(revision)) throw new Error('Expected the release commit SHA');
if (!/^[a-z0-9][a-z0-9.-]*(?::[0-9]+)?\/[a-z0-9][a-z0-9_-]*$/.test(prefix)) throw new Error('Invalid registry/owner prefix');
// Resolve every source to a digest and check every destination before writes.
const plan = images.map(image => {
const repository = `${prefix}/${image}`;
const digest = client.digest(`${repository}:sha-${revision}`);
const source = `${repository}@${digest}`;
if (client.revision(source) !== revision) throw new Error(`Image revision does not match Git tag: ${image}`);
const destination = `${repository}:${tag}`;
const existing = client.digest(destination, true);
if (existing !== null && existing !== digest) throw new Error(`Refusing to overwrite released image: ${destination}`);
return {source, destination, digest};
});
for (const item of plan) {
// Recheck before writing. Registry tag protection/serialized releases are
// still required: the registry does not offer a portable compare-and-swap.
const existing = client.digest(item.destination, true);
if (existing !== null && existing !== item.digest) throw new Error(`Release changed concurrently: ${item.destination}`);
if (existing === null) client.copy(item.source, item.destination);
if (client.digest(item.destination) !== item.digest) throw new Error(`Promoted digest mismatch: ${item.destination}`);
log(`${item.destination} -> ${item.digest}`);
}
return plan;
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
try {
const ref = process.env.RELEASE_REF || '';
const tag = imageTag(ref);
if (process.argv[2] === '--validate') {
console.log(`Release ${ref.slice('refs/tags/'.length)}; container tag ${tag}`);
} else if (process.argv.length !== 2) {
throw new Error('Usage: node tools/ci/release-images.mjs [--validate]');
} else {
promote({ref, revision: run('git', ['rev-parse', 'HEAD^{commit}']), prefix: `${process.env.REGISTRY}/${process.env.IMAGE_OWNER}`});
}
} catch (error) {
console.error(error.message);
process.exitCode = 1;
}
}
+116
View File
@@ -0,0 +1,116 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import {dockerClient, imageTag, images, promote} from './release-images.mjs';
test('SemVer release and prerelease tags', () => {
for (const version of ['0.1.0', '1.0.0', '1.2.3-rc.1', '1.0.0-0', '1.0.0-01a', '1.0.0-x-y-z.--', '12345678901234567890.0.1']) {
assert.equal(imageTag(`refs/tags/v${version}`), `v${version}`);
}
assert.equal(imageTag('refs/tags/v1.2.3-rc.1+build.001'), 'v1.2.3-rc.1_build.001');
});
test('reject malformed SemVer and ambiguous registry tags', () => {
for (const version of ['1', '1.2', '01.2.3', '1.02.3', '1.2.03', '1.2.3-01', '1.2.3-a.01', '1.2.3-', '1.2.3-a..b', '1.2.3+', '1.2.3+foo..bar', '1.2.3+foo+bar', '1.2.3_bad', '1.2.3\n', '1.2.3-RC.1', '1.2.3+BUILD', '1.2.3-'+ 'a'.repeat(128)]) {
assert.throws(() => imageTag(`refs/tags/v${version}`));
}
assert.throws(() => imageTag('refs/heads/v1.2.3'));
assert.throws(() => imageTag('refs/tags/1.2.3'));
});
const revision = 'a'.repeat(40);
const options = {ref: 'refs/tags/v0.1.0', revision, prefix: 'registry.example.test/anya'};
function registry() {
const entries = new Map(images.map((image, index) => [`${options.prefix}/${image}:sha-${revision}`, `sha256:${String(index + 1).repeat(64)}`]));
const copies = [];
const client = {
digest(ref, optional = false) {
if (entries.has(ref)) return entries.get(ref);
if (optional) return null;
throw new Error('source missing');
},
revision: () => revision,
copy(source, destination) {
copies.push({source, destination});
entries.set(destination, source.split('@')[1]);
},
};
return {client, entries, copies};
}
test('promotes three sources by digest and retry does not rewrite', () => {
const {client, copies} = registry();
const plan = promote(options, client, () => {});
assert.equal(copies.length, 3);
for (const item of plan) assert.ok(item.source.endsWith(`@${item.digest}`));
promote(options, client, () => {});
assert.equal(copies.length, 3);
});
test('missing source, wrong revision or existing release conflict prevents all writes', () => {
for (const failure of ['missing', 'revision', 'conflict']) {
const {client, entries, copies} = registry();
const last = `${options.prefix}/${images[2]}`;
if (failure === 'missing') entries.delete(`${last}:sha-${revision}`);
if (failure === 'revision') client.revision = () => 'b'.repeat(40);
if (failure === 'conflict') entries.set(`${last}:v0.1.0`, `sha256:${'f'.repeat(64)}`);
assert.throws(() => promote(options, client));
assert.equal(copies.length, 0);
}
});
test('partial promotion is safely resumable', () => {
const {client, copies} = registry();
const copy = client.copy;
client.copy = (source, destination) => {
if (copies.length === 1) throw new Error('registry unavailable');
copy(source, destination);
};
assert.throws(() => promote(options, client, () => {}), /unavailable/);
client.copy = copy;
promote(options, client, () => {});
assert.equal(copies.length, 3);
});
test('destination digest mismatch and concurrent overwrite are failures', () => {
const {client} = registry();
client.copy = () => {};
assert.throws(() => promote(options, client, () => {}));
const other = registry();
const get = other.client.digest;
let reads = 0;
other.client.digest = (ref, optional) => {
if (ref.endsWith(':v0.1.0') && ++reads > 3) return `sha256:${'f'.repeat(64)}`;
return get(ref, optional);
};
assert.throws(() => promote(options, other.client), /concurrently/);
assert.equal(other.copies.length, 0);
});
test('inspect distinguishes missing manifests from authorization and network errors', () => {
const ref = 'registry.example.test/anya/image:v0.1.0';
for (const message of [`docker failed: ERROR: ${ref}: not found`, 'docker failed: manifest unknown']) {
const client = dockerClient(() => { throw new Error(message); });
assert.equal(client.digest(ref, true), null);
assert.throws(() => client.digest(ref));
}
for (const message of ['unauthorized', 'TLS handshake timeout', 'no such host', '404 page not found']) {
const client = dockerClient(() => { throw new Error(message); });
assert.throws(() => client.digest(ref, true));
}
});
test('Docker adapter preserves manifest format and validates metadata', () => {
const calls = [];
const client = dockerClient((command, args) => {
calls.push([command, ...args]);
if (args.includes('{{json .Manifest}}')) return JSON.stringify({digest: `sha256:${'a'.repeat(64)}`});
if (args.includes('{{json .Image}}')) return JSON.stringify({os: 'linux', architecture: 'amd64', config: {Labels: {'org.opencontainers.image.revision': revision}}});
return '';
});
assert.equal(client.revision('source'), revision);
assert.equal(client.digest('source'), `sha256:${'a'.repeat(64)}`);
client.copy('source@sha256:abc', 'destination:v0.1.0');
assert.deepEqual(calls.at(-1), ['docker', 'buildx', 'imagetools', 'create', '--prefer-index=false', '--tag', 'destination:v0.1.0', 'source@sha256:abc']);
assert.throws(() => dockerClient(() => '{}').digest('source'), /Invalid registry digest/);
assert.throws(() => dockerClient(() => '{}').revision('source'), /linux\/amd64/);
});