Draft: Finalize the placeholder-references backfill BBMs
What does this MR do and why?
Stacked on !254095 (which is stacked on !253935 (merged)). Finalizes the three batched background migrations from !253935 (merged) that backfill reassignment_expires_at / expires_at / retention_expires_at, via ensure_batched_background_migration_is_finished.
Milestone 19.6, not 19.5. Per batched_background_migrations.md, a BBM can only be finalized after at least one required stop has passed since it was queued. These were queued at milestone 19.4; the next required stop after 19.4 is 19.5 (required upgrade stops for GitLab 19: 19.2, 19.5, 19.8, 19.11), so finalization is only valid once GitLab has moved past 19.5 - i.e. 19.6, matching the doc's own worked example (queued before a stop, finalized the release after it).
This isn't just a documentation reading - confirmed it by actually running FinalizeBackfillImportSourceUsersReassignmentExpiresAt on a local dev cluster still on 19.4-era code. It hit prevent_early_finalization! for real:
Batched migration should be finalized only after at-least one required stop from queuing it.
This is to ensure that we are not breaking the upgrades for self-managed instances.That check compares the BBM's queued milestone (from db/docs/batched_background_migrations/*.yml) against Gitlab::Database.upgrade_path.last_required_stop computed at runtime - not the finalize migration's own milestone label. It will keep failing on any environment still pre-19.5, and start succeeding once one is actually on 19.6+.
Do not merge until:
- !253935 (merged) and !254095 have merged.
- All three BBMs have actually completed on GitLab.com.
- GitLab.com (and the required-stop clock generally) has passed milestone 19.5.
Also updates finalized_by in the three db/docs/batched_background_migrations/*.yml files to point at these migrations.
Full context: #576118
References
- !253935 (merged) (base MR)
- !254095 (stacked in between - sync index)
- #576118
Database review data
Not applicable pre-merge - no schema changes, no new queries; this is a pure ensure_batched_background_migration_is_finished check against already-reviewed BBMs from !253935 (merged).
Screenshots or screen recordings
Not applicable — database schema change, no UI changes.
How to set up and validate locally
- Merge/rebase on top of the latest
georgekoltsov/finalize-placeholder-references-bbmsbase chain. bundle exec rails db:migrate- note this will fail with an early-finalization error unless your local environment'sGitlab::Database.upgrade_path.last_required_stopis already at or past 19.5 (it won't be, on any checkout still tracking current master pre-19.5 release).- Run the specs:
bundle exec rspec spec/migrations/20260908130000*_spec.rb spec/migrations/20260908130100*_spec.rb spec/migrations/20260908130200*_spec.rb
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.
Blocked until the three conditions above are met - do not merge on review approval alone.