۱. خلاصهٔ اجرایی

نتیجهٔ عملی: بایت‌هایی که در تست RC E2E را گذرانده‌اند، عیناً همان بایت‌هایی‌اند که با نام v1.7.0 منتشر می‌شوند.

۲. Tag و Digest چیستند؟

یک مرجع کامل ایمیج (Image Ref) معمولاً سه بخش دارد:

وقتی Tag و Digest هر دو وجود دارند، Pull بر اساس Digest انجام می‌شود و Tag فقط یک توضیح انسانی است. پس تغییر Tag روی «همان Digest» به‌معنای «همان ایمیج با نام جدید» است.

۳. Tag و Digest چه زمانی تغییر می‌کنند؟

نکته: شاخهٔ release-X.Y یک شاخهٔ Git است نه Tag ایمیج؛ در فایل اولیه Build آن به‌عنوان یک ردیف جدا آمده بود، ولی در مستند انتشار اشاره‌ای به Tag ایمیج مستقل برای آن نیست و حذف شده است.

۴. جریان Build، Promote و Mirror

flowchart LR
  PR["PR build
tag pr-N-sha
NEW digest"] --> MAIN["main build
tag main
NEW digest"]
  MAIN --> RC["cut-prerelease + tags.yaml
tag v1.7.0-rc.N
NEW digest"]
  RC --> E2E{"rc-e2e green?"}
  E2E -- yes --> PRM["promote-rc.yaml
rewrite tags in chart files
SAME digest"]
  PRM --> FIN["Finalize
retag by digest to v1.7.0
SAME digest"]
  FIN --> LATEST[":latest only if newest stable"]
  MAIN -. nightly .-> MIR["nightly-mirror.sh
copy by digest CI to release
SAME digest"]

sequenceDiagram
    autonumber
    participant CI as CI registry
    participant RC as release registry (rc)
    participant GIT as release-1.7.0 branch
    participant FIN as Finalize
    participant ST as release registry (stable)
    CI->>RC: tags.yaml builds v1.7.0-rc.2 (digest D1)
    RC-->>GIT: Prepare release commit pins digests D1
    GIT->>GIT: promote rewrites ":v1.7.0-rc.2@D1" to ":v1.7.0@D1"
    GIT->>GIT: second commit pins packages artifact digest
    GIT->>FIN: promote PR merged
    FIN->>RC: verify candidate and container digests
    FIN->>ST: retag by digest: v1.7.0 points to D1

۵. در فایل‌های Helm دقیقاً چه عوض می‌شود؟

مثال قبل و بعد از Promote

# شکل Diff در Promote PR
- image: infynex-api:v1.7.0-rc.2@sha256:9f3c…a1
+ image: infynex-api:v1.7.0@sha256:9f3c…a1

۶. مرجع‌های ایمیج کجا ذخیره می‌شوند؟

Commit ‏«Prepare release vX.Y.Z» فقط Digest و Tag Image را عوض می‌کند. فایل‌های لمس‌شده:

فایل اولیه چهار «شکل» ذخیره‌سازی را برمی‌شمرد و یک استثنا برای فایل‌های Vendor‌شده از بالادست (مثل DaemonSet ‏multus):

چیزهای عجیب‌نما اما عادی در Diff

• پکیج بدون تغییر: وقتی Cache کامل بوده و Base Imageها جابه‌جا نشده‌اند، Digest عیناً همان قبلی است. «بدون Diff» یعنی «Build نشده» نیست؛ اجرای گام Build را بررسی کنید.
• تغییر ناگهانی Tagهای ubuntu-container-disk-*: منبع بالادستی یک هدف متحرک است.
• تغییر رجیستری: اگر ایمیجی از یک رجیستری به دیگری منتقل شده، بخش رجیستریِ مرجع عوض می‌شود؛ این یک انتقال عمدی است.
• targetVersion را PR انتشار تغییر نمی‌دهد: این عدد قبلاً در یک Commit قابلیت بالا رفته؛ PR انتشار فقط Digest ایمیج Migrationها را ثابت می‌کند.

۷. استثنا: آرتیفکت packages و «ارجاع به خود»

علاوه بر ایمیج‌های کانتینر، پلتفرم یک آرتیفکت OCI به نام packages (درخت packages/) منتشر می‌کند. Digest این آرتیفکت در Promote جدید است، چون درخت بازنویسی شده است:

1. Promote درخت را بازنویسی می‌کند (Tag ← 1.7.0) و زیر یک Tag موقت promotion-* منتشر می‌کند.
2. Commit دوم Digest تغییرناپذیر همین Candidate را در Installer ثابت می‌کند.
3. آرتیفکت نمی‌تواند Digest خودش را در خودش داشته باشد؛ این «ارجاع به خود» غیرممکن است و هنگام تأیید نادیده گرفته می‌شود.

۸. اسکریپت‌ها و workflowها

ردیف‌های «فایل اولیه» در این گفتگو راستی‌آزمایی نشده‌اند. فایل docs/alm-versioning-release-guide.md که در فایل اولیه آمده بود هم همین‌طور؛ در مستند انتشار چنین نامی نیست و از جدول حذف شد.

۹. کنترل در سطح چارت است یا کنترلرهای کلاستر؟

• کنترلرهای کلاستر فقط مصرف‌کننده‌اند: چارت رندر می‌شود و Deployment/StatefulSet/Pod با image: repo:tag@sha256:… ساخته می‌شود. کنترلر هیچ‌چیز را به values.yaml یا فایل چارت بازنمی‌نویسد.
• بازنویسی Tag، Retag، Mirror و تأیید Digest همه با اسکریپت‌های Shell و workflowهای CI انجام می‌شوند.

flowchart LR
  CI["CI scripts and workflows"] -->|rewrite tag| CH["Helm chart files"]
  CI -->|retag by digest| REG["OCI registry"]
  CH -->|helm template| MAN["rendered manifests"]
  MAN -->|deploy| K8S["Kubernetes cluster"]
  K8S --> CTL["controllers (read only)"]
  CTL -. never write .-> CH

۱۰. Nightly Mirror

Nightly یک کپی قابل‌نصب از main روی رجیستری Release است؛ نه Build دوباره و نه Release. Build هر Push روی main قبلاً در رجیستری CI ساخته شده؛ nightly.yaml آن را ارتقا می‌دهد و نصب‌پذیری‌اش را اثبات می‌کند:

1. mirror: Commit دقیقی که packages:main از آن ساخته شده پیدا می‌شود و تمام ایمیج‌های اجزای پلتفرم با Digest کپی می‌شوند. آرتیفکت packages و Chart نصب‌کننده با Tag زیر منتشر می‌شوند: 0.0.0-nightly.<YYYYMMDD>.<run-id>.<attempt> به‌علاوهٔ Tag شناور nightly.
2. build-disk: دیسک Talos از Imager بالادستی ساخته و منتشر می‌شود.
3. e2e: مجموعهٔ کامل اپلیکیشن‌ها روی نتیجه اجرا می‌شود.

برای Nightly هیچ GitHub Release و Tag ماژول Go ساخته نمی‌شود، و retention.yaml نسخه‌های قدیمی را پاک می‌کند (۱۴ نسخهٔ اخیر هر بسته می‌ماند).

۱۱. خودتان چطور بررسی کنید؟

با crane می‌توانید ثابت بودن Digest را عملاً ببینید:

# Digest مربوط به هر دو Tag باید یکسان باشد
crane digest ghcr.io/infynex-io/infynex/infynex-api:v1.7.0-rc.2
crane digest ghcr.io/infynex-io/infynex/infynex-api:v1.7.0

# مرجع با Digest باید Pull شود (مثلاً هنگام بازبینی Promote PR)
crane manifest ghcr.io/infynex-io/infynex/infynex-api@sha256:9f3c…a1 | head

# فقط Tag عوض شده، Digest نه: Diff شاخهٔ Promote
git diff release-1.7...release-1.7.0 -- 'packages/**/values.yaml' | grep -E '^[+-].*image'

۱۲. پرسش‌های پرتکرار

برای جزئیات کامل مراحل Promote و Finalize به «راهنمای انتشار نسخه در پلتفرم Infynex» مراجعه کنید.