#7067·tinacms

Deploy schema gate should wait for schemaSha convergence, not a one-shot compare

Author: kulesyCreated Jun 18, 2026Updated Sep 17, 2026
Labelsenhancementdx@tinacms/cli

Pain

The schema check is an instantaneous compare against an eventually-consistent backend. Indexing is async (webhook -> SQS -> Lambda, seconds to minutes), so the remote schemaSha cannot match immediately after a schema change. A one-shot check races the re-index and false-fails even when everything is correct. Users work around it with --skip-cloud-checks, which disables the check everywhere, including where it is legitimate.

Approach

Post-push, poll GET /db/{clientId}/{branch}/schemaSha until the remote converges with the locally computed value (bounded timeout), then pass. Error only if it never reconciles, which now signals a real incompatibility rather than indexing lag.

When it does fail, name the likely cause: report the local-vs-remote @tinacms/graphql version delta (the remote side is tracked in Metadata.<branch>.tinaVersion) so a version skew is stated, not guessed.

Acceptance criteria

  • The deploy-time schema check polls for schemaSha convergence with a bounded timeout instead of comparing once.
  • It cannot false-fail on async indexing lag.
  • On non-convergence, the error is clear and actionable and reports the local-vs-remote @tinacms/graphql version delta (ties into #6971 / #6562 / tinacms/tinacloud#3723).

Part of #7065.