vtex-io-storefront-theme-versioning

ストアフロントテーマのバージョン管理、インストール、ロールバック

このスキルを使用する場合

コンテンツを保持するストアフロントアプリ（vendor.store-theme のようなテーマ、または store/blocks.json、store/routes.json、store/templates/、store/contentSchemas.json のいずれかを含むアプリ）のバージョンが master で変更される場合は、常にこのスキルを使用してください。

• vtex release patch | minor | major を使用してテーマアプリのバージョンを上げる場合
• テーマアプリで vtex publish / vtex deploy を実行する場合
• 本番アカウントに対して vtex install [email protected] を実行する場合
• master と異なるバージョンのテーマがインストールされたワークスペースを昇格する場合
• ストアフロントのコンテンツがすべて「失われた」デプロイからの復旧を計画する場合
• ストアフロントテーマに関わる開発者のデプロイスクリプトをレビューする場合

次の場合は、このスキルを使用しないでください。

• interfaces.json によるブロックの登録 — vtex-io-render-runtime-and-blocks を使用してください
• react/ 配下の購入者向けコンポーネントコード — vtex-io-storefront-react を使用してください
• manifest.json#settingsSchema 配下のアプリレベルの設定 — vtex-io-app-settings を使用してください
• Master Data のスキーマのバージョン管理 — vtex-io-masterdata-strategy を使用してください

判断ルール

• store/ 配下にコンテンツを含むアプリ（テーマアプリや多くのストアフロントアプリ）は、コンテンツ保持アプリとして扱ってください。インストール済みの MAJOR バージョンは、プラットフォームがそのアプリによって宣言されたブロックに対して、マーチャントがこれまでに保存したすべての Site Editor の変更を保存・検索する際に使用するキーの一部です。
• Site Editor のコンテンツ、カスタムルート、テンプレート、およびテンプレートごとのレンダーキャッシュは、vtex.pages-graphql によって [email protected]:template 形式のキーで保存されます。例：[email protected]:store.home、[email protected]:store.product。
• patch（0.0.61 → 0.0.62）と minor（0.1.0 → 0.2.0）では同じキーが再利用されるため、新しいバージョンからも同じマーチャントコンテンツが参照されます。major（0.x → 5.x）ではキーが変わります。テーマコードがそれ以外は同一であっても、新しいメジャーバージョンにはマーチャントコンテンツが一切ありません。
• vtex.pages-graphql が有効なメジャーバージョンのコンテンツを見つけられない場合、デフォルトの vtex.store-theme コンテンツにフォールバックします。顧客のアプリがインストールされ、レンダリングされているにもかかわらず、サイトには「VTEX のデフォルトテーマ」のコンテンツが表示され、見た目が明らかに劣化します。
• 可能な限り、コンテンツ保持アプリに対する vtex release major は避けてください。マーチャントコンテンツを自動的に引き継ぐため、変更は現在のメジャーバージョン内で patch または minor として行うことを優先してください。
• ブロック、ルート、またはテンプレートの構造変更によりメジャーバージョンの更新が避けられない場合は、プロモートする前に [email protected] の updateThemeIds ミューテーションを使って、古いメジャーバージョンから新しいメジャーバージョンへマーチャントコンテンツを移行してください。このミューテーションは、vendor.app@{oldMajor}.x から vendor.app@{newMajor}.x へ、すべての Site Editor の編集内容、Pages、Redirects のキーを1回の操作で付け替えます。これは開発者が利用できる公式の復旧手段です。コンテンツを手動で作り直す必要があると決めつけないでください。
• 新しいテーマのメジャーバージョンは、プロモートする前に、必ずproduction フラグ付きの dev ワークスペース（vtex use rollout-workspace --production。このコマンドはワークスペースの作成と切り替えを1ステップで実行します）にインストールして検証してください。リンクするだけでは不十分です。vtex link は公開済みアーティファクトを検証せず、vtex install + vtex workspace promote と同じコンテンツキーの動作も再現しません。
• production フラグ付きの dev ワークスペースで、新しいメジャーバージョンの vtex install を実行した後、vtex workspace promote を実行する前に、GraphQL Admin IDE から [email protected] に対して updateThemeIds を実行してください（vtex install [email protected] の後に vtex browse admin/graphql-ide を実行します）。これにより、そのワークスペース内の Site Editor、Pages、Redirects は新しいメジャーバージョンで解決され、プロモート時にワークスペースとともに引き継がれます。
• vtex workspace promote は原子的な切り替えとして扱ってください。updateThemeIds の実行後、dev ワークスペースの全ページ（ホーム、PDP、PLP、部門ページ、検索、カスタムルート、アカウント、チェックアウトのエントリーポイント）をスモークテストしてください。dev ワークスペースに問題があれば、master にも問題が生じます。
• Apps Registry に公開されたバージョンが、想定しているソースと一致することを確認してください。よくある失敗パターンは、誤って簡略化されたボイラープレートを公開してしまうことです。レジストリのバージョンは正常にインストールされますが、既存の Site Editor コンテンツが参照するカスタムブロックが含まれていません。updateThemeIds ではブロック不足の問題は解決できず、既存コンテンツのキーを付け替えることしかできません。
• 以前のメジャーバージョンにダウングレードする場合（例：5.x → 4.x）にも、同じ updateThemeIds の手順が必要です。このミューテーションは MAJOR の境界を越えて、どちらの方向にもコンテンツを移動します。
• vtex workspace promote は master の vtex.pages-graphql VBase コンテンツを消去しません。このサービスは MineWinsConflictsResolver を使ってマージします。これは base（dev ワークスペースがフォークした時点の master の状態）、master（現在の master）、mine（dev ワークスペース）による3方向マージです。dev ワークスペースで変更されていない master のキーは保持され、競合するキーは dev ワークスペース（「mine が優先」）の内容で解決されます。ロールアウト期間中に master への競合する書き込みが最小限になるよう計画してください。たとえば、dev ワークスペースの準備中は、master でのマーチャントによる Site Editor の編集を一時停止します。
• MineWinsConflictsResolver が本番環境で競合を解決するたびに、vtex.pages-graphql は base、master、mine の分単位のスナップショットを、隣接する userData_backup VBase バケットに自動で書き込みます。これは io_vtex_logs インデックスの subject: "conflicts_resolution" として記録されます。プロモートによって望ましくない内容がマージされた場合、このスナップショットが復旧元になりますが、スモークテストの代わりにはなりません（解決すべき競合がない場合、バックアップは書き込まれません）。このバックアップは VTEX サポートへのエスカレーションに備えるセーフティネットとして扱い、通常のセルフサービス復元には使用しないでください。

厳守すべき制約

制約：コンテンツを保持するアプリのメジャーバージョンを上げる場合、プロモート前に updateThemeIds による移行が必要です

Store Framework のコンテンツを所有するアプリで vtex release major を実行する場合（または MAJOR.x の境界を越えるバージョン変更を行う場合）、本番フラグ付きの開発ワークスペースで [email protected] の updateThemeIds ミューテーションを使用し、旧メジャーバージョンから新メジャーバージョンへマーチャントのコンテンツを移行してからでなければ、master にプロモートしてはなりません。新しいメジャーバージョンは、vtex.pages-graphql から見るとコンテンツが空の状態で始まります。updateThemeIds を実行せずに master にプロモートすると、Site Editor の編集に依存するすべてのページで、ストアフロントがデフォルトのテーマコンテンツにフォールバックします。

これが重要な理由

vtex.pages-graphql は、マーチャントが所有するすべてのルート、テンプレート、Site Editor の編集内容、Page／Redirect エントリーを [email protected]:template でキー付けします。パッチまたはマイナーバージョンの更新ではキーが維持されますが、メジャーバージョンの更新ではキーが無効になります。メジャーバージョンを上げると、マーチャントがこれまでに保存した Site Editor の変更はすべて、新しいメジャーバージョンではリゾルバーから見えなくなり、ストアフロントはデフォルトの vtex.store-theme コンテンツにフォールバックします。開発者が実行できる公式の修正方法は updateThemeIds ミューテーションです。これにより、すべての Site Editor の編集内容、Pages、Redirects が、1 回の操作で旧メジャーバージョンから新メジャーバージョンへキー付けし直されます。これを省略したり（または開発者がコンテンツを手動で作り直す必要があると思い込んだり）すると、買い物客が利用するストアフロントの品質が低下します。

検出

本番アカウントで vtex install [email protected] を実行する前に、X を現在インストールされているメジャーバージョン（vtex ls --production | grep store-theme）と比較します。X が異なる場合は、作業を中止してください。新しいメジャーバージョンをインストールした後、プロモートする前に、本番フラグ付きの開発ワークスペースで updateThemeIds による移行を実行してください。

また、開発者が store/blocks.json、store/routes.json、store/templates/、store/contentSchemas.json のいずれかを含むアプリで vtex release major を実行しようとしている場合も、作業を中止してください。まず、構造上の変更を patch または minor で実現できないことを確認します。メジャーバージョンの更新が避けられない場合は、updateThemeIds の手順を明示的に計画してください。

正しい例

vtex use theme-rollout --production            # creates and switches to a production-flag dev workspace
vtex install [email protected]
vtex install [email protected]        # required to access the GraphQL IDE
vtex browse admin/graphql-ide
# In the IDE, select the app `[email protected]` from the dropdown and run:
#
# mutation {
#   updateThemeIds(
#     from: "[email protected]",
#     to:   "[email protected]"
#   )
# }
#
# Expected response: { "data": { "updateThemeIds": true } }
# Validate Site Editor, Pages, and Redirects in this workspace, then:
vtex workspace promote

誤った例

vtex release major
vtex publish
vtex install [email protected]
# installed straight to master — no merchant content is visible under @5.x
# and the storefront falls back to default vtex.store-theme content

制約：コンテンツを保持するアプリのバージョンを、開発ワークスペースでのスモークテストなしに master へ直接インストールしてはなりません

master 上でコンテンツを保持するアプリのインストール済みバージョンを変更する場合は、必ず最初に本番フラグ付きの開発ワークスペース（vtex use $name --production）で実施し、全ページを対象にスモークテストを行ってから、vtex workspace promote でプロモートしてください。

これが重要な理由

master は公開されているストアフロントです。テーマを master に直接インストールすると、新しいバージョンが即座にすべての買い物客に公開されます。インストールによってブロックの欠落、新しいメジャーバージョンでのコンテンツ領域の空白、または公開用に縮小されたアーティファクトが判明した場合、復旧するには負荷がかかった状態でロールバックするしかありません。本番フラグ付きの開発ワークスペースは master と同じデータに対してレンダリングを行うため、買い物客に影響を与えることなく同じ問題を検出できます。

検出

開発者のコマンド実行順序で、アクティブなワークスペースが master の状態で vtex install を実行しようとしている場合は、作業を中止してください。まず本番フラグ付きの開発ワークスペースに切り替えてください。

正しい例

vtex use theme-rollout-2026-04 --production    # creates and switches to a production-flag dev workspace
vtex install [email protected]
# if this install crosses a MAJOR boundary, run updateThemeIds before smoke tests.
# fetch home, PDP, PLP, search, custom routes from $workspace--$account.myvtex.com
# only after smoke tests pass:
vtex workspace promote

誤った例

vtex use master
vtex install [email protected]
# any failure is now public

制約：公開されたアーティファクトが想定したソースと一致することを確認します

コンテンツを保持するアプリの新しい公開バージョンを master にインストールする前に、Apps Registry 内のアーティファクトに、アクティブなマーチャントコンテンツが参照するブロックが実際に含まれていることを確認してください。vtex publish が成功しても、アーティファクトにマーチャントのカスタマイズが含まれているとは限りません。

これが重要な理由

よくある失敗パターンは、簡素化されたリポジトリ、またはマーチャントが何か月も編集してきたカスタムブロックが失われたベーステーマのフォークから公開してしまうことです。インストールは成功しますが、pages-graphql はマーチャントの保存済みコンテンツが参照するブロックを解決できず、ストアフロントはデフォルトのコンテンツにフォールバックします。アーティファクトとコンテンツが一致しません。

検出

公開バージョンが、アクティブなテーマが参照するカスタムブロックを含まないリポジトリからビルドされていた場合は、STOP。正しいソースから再公開してください。updateThemeIds マイグレーションはコンテンツのキーを付け替えるだけで、欠落したブロック ID は解決できません。そのため、簡素化されたアーティファクトは、マイグレーションが成功した後もデフォルトのコンテンツにフォールバックします。

正しい例

# pull the published artifact and confirm it ships the custom blocks
vtex apps files [email protected] store/ | grep -E 'umMaisUm|customHeader'
# matches the block IDs the active theme depends on

誤った例

vtex publish
vtex install [email protected]
# published artifact is the boilerplate fork; it is missing every custom block
# referenced in the merchant's stored content

制約：vtex workspace promote は pages-graphql VBase の 3 者間マージ（mine-wins）として扱い、全置換と見なさないでください

vtex workspace promote は、master の vtex.pages-graphql VBase コンテンツを破壊的に置き換える処理ではなく、dev ワークスペースと master の間のマージとして計画する必要があります。サービスは @vtex/api の MineWinsConflictsResolver を使用します。base（dev ワークスペースのフォーク元となった master の状態）、master（現在の master）、mine（dev ワークスペース）の差分を取り、競合は dev ワークスペースを優先して解決します。

これが重要な理由

dev ワークスペースが変更していない master のキーは、promote 後も保持されます。競合するキー（フォークした時点以降に master と dev ワークスペースの両方で編集されたもの）は、dev ワークスペースの値で上書きされます。テーマの展開では、実務上、次の 2 点に注意してください。

1. dev ワークスペースの準備中もマーチャントが master で Site Editor を編集し続けると、dev ワークスペースも変更するキーに対する編集は、promote 時に失われます。
2. dev ワークスペースで updateThemeIds を実行すると、dev ワークスペースが新しいメジャーバージョンのコンテンツマップを所有します。これを promote すると、キーが付け替えられた Site Editor の編集内容、Pages、Redirects が mine-wins により master に問題なく移行されます。

本番環境では、競合を解決するたびに、vtex.pages-graphql 内の隣接する userData_backup VBase バケットへ、base、master、mine の 1 分単位のスナップショットが書き込まれます。ログには subject: "conflicts_resolution" と記録されます。解決する競合がない場合、バックアップは書き込まれません。そのため、安全確認の主な手段は引き続きスモークテストです。

検出

展開計画が promote による master コンテンツの「置き換え」を前提としている場合は、STOP。マージ計画として説明し直してください。dev ワークスペースが変更するキー、同じ期間に master が変更する可能性の高いキー、および競合の解決方法を明確にします。展開期間中にマーチャントが master の Site Editor を積極的に編集している場合は、STOP。その編集を一時停止するか、展開期間を短縮するか、上書きされるキーを文書化してください。

正しい例

Coordinate the rollout window with the merchant ops team:
- Pause Site Editor edits on master from the moment `updateThemeIds`
  runs in the dev workspace until `vtex workspace promote` completes.
- Smoke-test in the dev workspace, then promote.
- After promote, validate Storefront → Site Editor, Pages, Redirects
  on master.

If a conflict-resolution log appears (subject: "conflicts_resolution"),
record the backup paths surfaced by pages-graphql in `io_vtex_logs`.
The snapshot lives in the `userData_backup` bucket of vtex.pages-graphql
and can be fetched via the VBase v2 API for support escalation.

誤った例

"Promote will replace master, so we don't need to coordinate."
- Merchants keep editing Site Editor in master during the rollout.
- Promote merges those edits with mine-wins; every conflicting key is
  silently overwritten by the dev workspace value.
- Without a smoke-test or coordination, the lost edits are not noticed
  until shoppers report missing content.

推奨パターン

master にインストールされたコンテンツを保持するアプリを変更する場合の推奨デプロイフロー：

1. Decide the SemVer bump deliberately
   - patch  → bug fix, no block contract change
   - minor  → new optional block, backward-compatible additions
   - major  → ANY structural change that breaks an existing block contract
              (avoid when possible; requires the updateThemeIds migration)

2. vtex release [patch|minor|major]
   vtex publish

3. Switch to a production-flag dev workspace
   (vtex use both creates and switches in one step)
   vtex use theme-rollout-YYYY-MM-DD --production

4. Install the new version in the dev workspace
   vtex install [email protected]

5. If the bump crosses a MAJOR boundary (including downgrades such as 5.x → 4.x):
   a. vtex install [email protected]   (if not already installed)
   b. vtex browse admin/graphql-ide
   c. In the IDE, select the app `[email protected]` from the dropdown
   d. Run:
        mutation {
          updateThemeIds(
            from: "{appVendor}.{appName}@{oldMajor}.x",
            to:   "{appVendor}.{appName}@{newMajor}.x"
          )
        }
      Keep the literal "x" in both keys; do not replace it with a minor or
      patch number or the mutation silently fails.
   e. Expected response: { "data": { "updateThemeIds": true } }
   If the bump is patch or minor inside the same major, skip this step —
   content keys are preserved automatically.

6. Smoke-test in the dev workspace against the full page set
   - $workspace--$account.myvtex.com/             (home)
   - $workspace--$account.myvtex.com/<pdp-slug>/p (product)
   - $workspace--$account.myvtex.com/<category>   (PLP)
   - $workspace--$account.myvtex.com/<dept>       (department)
   - $workspace--$account.myvtex.com/<search>?_q  (search)
   - any /institucional/* or other custom routes
   - VTEX Admin → Storefront → Site Editor, Pages, Redirects
   - account, login, cart, checkout entry

7. If anything is wrong: stop. Do not promote. Investigate.
   If everything renders correctly:
   - Coordinate the promote window with the merchant ops team so that
     no Site Editor edits land on master between `updateThemeIds` in
     the dev workspace and `vtex workspace promote`. Promote performs
     a 3-way mine-wins merge against pages-graphql VBase, so any
     conflicting master edit will be overwritten by the dev workspace.
   - vtex workspace promote

8. Re-test on $account.myvtex.com (master) and the public domain.
   - Validate Storefront → Site Editor, Pages, Redirects on master.
   - If the public CDN serves stale content, validate with cache-busting
     query strings; the edge will refresh on its normal TTL.
   - If `io_vtex_logs` shows a `subject: "conflicts_resolution"` entry
     for `vtex.pages-graphql` in this account around the promote time,
     record the listed backup paths. They live in the `userData_backup`
     bucket of pages-graphql and can be fetched via the VBase v2 API
     if a recovery is needed later.

9. Keep the dev workspace for at least one business day in case a fast
   re-promote is needed.

master へのメジャーバージョンのインストールで問題が発生した場合の推奨緊急ロールバック：

1. vtex use rollback-YYYY-MM-DD --production
   (vtex use both creates and switches; there is no `vtex workspace create`)
2. vtex install vendor.store-theme@<previous major version>
3. If the rollback crosses a MAJOR boundary (it almost always does), run
   updateThemeIds in [email protected] to migrate stored Site Editor
   edits, Pages, and Redirects from the broken major back to the previous
   major:

     mutation {
       updateThemeIds(
         from: "{appVendor}.{appName}@{brokenMajor}.x",
         to:   "{appVendor}.{appName}@{previousMajor}.x"
       )
     }

4. Smoke-test the rollback workspace end-to-end (storefront pages and
   VTEX Admin → Storefront → Site Editor, Pages, Redirects).
5. vtex workspace promote

If `updateThemeIds` returns false, the GraphQL IDE shows an error, or
content does not appear after migration, escalate to VTEX support
before promoting; do not promote a workspace whose Site Editor content
has not been validated.

If a previous promote merged in something unwanted, before re-promoting
check `io_vtex_logs` for a `subject: "conflicts_resolution"` entry on
`vtex.pages-graphql` for this account around the original promote
time. The entry lists per-minute snapshot paths inside the
`userData_backup` bucket (`store/templates.{base|master|mine}.<TS>.json`,
`store/content.{...}.json`, `store/routes.{...}.json`) which can be
fetched through the VBase v2 API:

   GET https://infra.io.vtex.com/vbase/v2/{account}/{workspace}/
       buckets/vtex.pages-graphql/userData_backup/files/{path}

This recovery path requires an admin auth token and is documented in
`vtex/pages-graphql` `TROUBLESHOOTING.md`. Treat it as a support-led
escalation, not a routine self-service step, and always test the
restored payload in a non-master workspace first.

コンテンツキーの動作を理解するための推奨される考え方：

Patch / minor bump
   acme.store-theme @ 0.0.61  →  0.0.62
   storage key prefix unchanged: [email protected]:*
   merchant content carries over automatically

Major bump
   acme.store-theme @ 0.0.61  →  5.0.0
   storage key prefix changes: [email protected]:*  →  [email protected]:*
   the new major starts empty from the resolver's point of view
   run updateThemeIds in [email protected] inside the production-flag
   dev workspace to rekey Site Editor edits, Pages, and Redirects from
   [email protected] to [email protected], then promote

よくある失敗例

• バージョン番号を「整理する」ためにテーマで vtex release major を実行し、プロモート前に updateThemeIds マイグレーションが必要だと気づかない。
• 開発ワークスペースが「同じように見えた」ため、新しいメジャーバージョンのテーマを master に直接インストールする。
• アクティブなテーマが依存するカスタムブロックを含まないフォーク済みリポジトリから公開する。updateThemeIds はコンテンツのキーを付け替えますが、存在しないブロック ID は解決できません。
• コンテンツを保持するアプリで、vtex link を vtex install と同等に扱う。link では公開済みアーティファクトの解決経路や、メジャーバージョンのキーに基づくコンテンツ検索は検証できません。
• エンドツーエンドでスモークテストを一度も行っていないワークスペースから vtex workspace promote を実行する。
• 先に updateThemeIds を実行せずにメジャーバージョンを上げてプロモートし、以前は Site Editor の編集内容に依存していたすべてのページで、デフォルトの vtex.store-theme コンテンツがストアフロントに表示される。
• 存在しない vtex workspace create コマンドを実行しようとする。CLI は vtex use {workspaceName} --production の副作用としてワークスペースを作成します。このコマンドだけで作成と切り替えの両方が行われます。
• updateThemeIds の引数にあるリテラルの x をマイナーまたはパッチバージョンに置き換える（[email protected] ではなく [email protected] を指定する）。このミューテーションにはメジャーバージョンを x で指定する形式が必要で、それ以外の場合は何もせずに終了します。
• GraphQL IDE のドロップダウンで誤ったアプリを選択した状態で updateThemeIds を実行する。このミューテーションは [email protected] にのみ存在します。
• プロモート直後に公開ドメインで修正をすぐ確認できると考える。CloudFront は古いコンテンツを配信するため、検証時は ?utm_source=<value> などのキャッシュを無効化するパラメーターを使い、エッジキャッシュを回避してください。
• ダウングレード（たとえば 5.x → 4.x）も MAJOR の境界をまたぐため、プロモート前に独自の updateThemeIds 実行が必要なことを忘れる。
• vtex workspace promote によって、master の vtex.pages-graphql VBase コンテンツが消去され、開発ワークスペースの内容で再度埋められると思い込む。そうはなりません。mine-wins の 3-way マージが行われるため、開発ワークスペースで変更されていない master のキーは残り、開発ワークスペースでも変更された master のキーは通知なく上書きされます。master での Site Editor の同時編集が失われないよう、マーチャント運用チームとロールアウトの時間帯を調整してください。
• vtex.pages-graphql 内の userData_backup バケットを通常の復元先として扱う。これは競合が解決されたときにのみ書き込まれ（競合がなければバックアップされません）、管理者レベルの認証と VBase v2 API が必要です。また、サポート主導のトラブルシューティング用のものであり、スモークテストや updateThemeIds フローの代わりにはなりません。

レビューチェックリスト

• 提案されているバージョンの更新は、SemVer のルールに照らして patch、minor、major のいずれに正しく分類されていますか？
• 更新がメジャーバージョンの境界をまたぐ場合、production フラグ付きの開発ワークスペースで updateThemeIds の移行手順が文書化されていますか（ダウングレードを含む、どちらの方向も）？
• インストール先は、まず production フラグ付きの開発ワークスペース（vtex use $name --production）になっていますか（master への直接インストールは行っていませんか）？
• 更新がメジャーバージョンの場合、GraphQL Admin IDE から [email protected] に対して updateThemeIds を実行し、応答が { "updateThemeIds": true } になっていますか？
• 公開されたアーティファクトに、アクティブなテーマが依存するカスタムブロックが含まれていることを確認しましたか？
• 開発ワークスペースで、ホーム、PDP、PLP、部門、検索、カスタムルート、アカウント、チェックアウトの入口、および Storefront モジュール（Site Editor、Pages、Redirects）を対象にスモークテストを実施しましたか？
• 3 者間のマージでは mine-wins になるため、開発ワークスペースでの updateThemeIds から vtex workspace promote までの間に、Site Editor での同時編集が master に反映されないよう、ロールアウト期間を調整しましたか？
• promote 後、このアカウントの vtex.pages-graphql に対して subject: "conflicts_resolution" のエントリーがないか io_vtex_logs を確認し、存在する場合は、サポートへのエスカレーションに備えて、記載されている userData_backup のパスを記録しましたか？
• 再度すばやく promote する必要が生じた場合に備えて、promote 後も開発ワークスペースを少なくとも 1 営業日保持していますか？

関連スキル

• vtex-io-app-contract — manifest のコントラクトで何を宣言すべきか、またコンテンツを保持するアプリにとってメジャーバージョンの更新がなぜコントラクトを破壊する変更なのかが問題となる場合。
• vtex-io-storefront-theme-app — テーマアプリが実際に所有するもの（store/blocks.json、store/routes.json、ページテンプレート）と、それらのファイルがマーチャントの Site Editor コンテンツとどのように関係するかが問題となる場合。
• vtex-io-render-runtime-and-blocks — テーマ内のブロック名が React コンポーネントにどのように解決されるか、またアクティブなメジャーバージョンでブロックが欠落するとレンダリングに失敗する理由が問題となる場合。
• vtex-io-data-access-patterns — あるデータを Site Editor で管理すべきか、あるいはアプリ設定、Master Data、その他のストアに置くべきかが問題となる場合。

参考資料

• Manifest — vendor、name、version が、ストアフロントのコンテンツキーで使用されるアプリの識別情報をどのように構成するかを説明します。
• アプリのバージョン管理 — vtex release と、バージョンの更新によって後続のコンテンツキーが維持されるか無効になるかを決める SemVer のルールについて説明します。
• アプリの公開 — vtex publish によって、vtex install でインストールされるアーティファクトがどのように生成されるかを説明します。
• アプリのインストール — vtex install のワークスペーススコープと、現実的なテストを行うには開発ワークスペースを production-flag にする必要がある理由を説明します。
• Production Workspace の作成 — vtex use {workspaceName} --production は、production-flag のワークスペースを作成し、そこに切り替える両方の操作を行う唯一のコマンドです。
• ワークスペースの master への昇格 — vtex workspace promote を使用して、production-flag の開発ワークスペースから master へアトミックに切り替える方法を説明します。
• メジャーなテーマ更新後の CMS 設定の移行 — [email protected] の updateThemeIds ミューテーションに関する公式手順です。GraphQL IDE の設定と、引数にリテラルの MAJOR.x 形式を使用する方法も説明します。
• vtex/pages-graphql の TROUBLESHOOTING.md — MineWinsConflictsResolver が vtex.pages-graphql の userData_backup バケットに、base、master、mine のスナップショットを毎分書き込む方法と、サポート主導の復旧に向けて VBase v2 API 経由で取得する方法を説明します（VTEX 内部リポジトリ）。
• Store Framework — テーマアプリが store/ のコンテンツを所有する理由と、Store Framework がレンダリング時にそのコンテンツをどのように利用するかを説明します。