Write state propagation outbox row on namespace transitions

What does this MR do and why?

Problem: When a group is archived or scheduled for deletion, its subgroups should follow. The pieces to do that already exist (an outbox table, Namespaces::StatePropagationService, Namespaces::StatePropagationWorker), but nothing ever writes to the outbox. So today subgroups never get their parent's new state.

Solution: When a group's state changes, write one outbox row describing the change, in the same transaction, and start the worker after commit. The worker then walks the subgroups and updates them.

How a state change reaches subgroups

sequenceDiagram
    participant U as User action
    participant G as Group (state machine)
    participant O as Outbox table
    participant W as StatePropagationWorker
    participant D as Subgroups

    U->>G: archive
    activate G
    Note over G,O: one transaction
    G->>G: state = archived
    G->>O: insert row (source: ancestor_inherited, target: archived)
    deactivate G
    G-->>W: perform_async (only after commit)
    W->>O: read and claim row
    W->>D: move matching subgroups to archived
    W->>O: delete row

Because the state change and the row are written in one transaction, they either both happen or neither does (ADR 003). The worker is only enqueued once the commit succeeds, so it never runs for a change that was rolled back.

What the row records

Each row stores two states:

  • target_state: the group's new state.
  • source_state: the state the subgroups currently have from this group. The worker uses it to decide which subgroups to change, and (since !258166 (merged)) whether to save or clear their previous state.

Usually source_state is simply the state the group just left. The exception is the short-lived "in progress" states (deletion_in_progress, transfer_scheduled, transfer_in_progress). Subgroups never get these states, so the group's previous state is the one that matters. That state is already saved when the group enters the in-progress state, and this MR reads it from there.

Example: cancelling a deletion that already started

stateDiagram-v2
    direction LR
    ancestor_inherited --> deletion_scheduled: schedule deletion
    deletion_scheduled --> deletion_in_progress: start deletion
    deletion_in_progress --> ancestor_inherited: cancel deletion

If the row used the state the group just left, it would say source: deletion_in_progress. The worker can't use that (subgroups were never in it), so it would drop the row:

Using the state just left (source_state = deletion_in_progress):
Parent (deletion_in_progress → ancestor_inherited)
└── Subgroup (deletion_scheduled) → ❌ stays deletion_scheduled

With it (source_state = deletion_scheduled, saved at "start deletion"):
Parent (deletion_in_progress → ancestor_inherited)
└── Subgroup (deletion_scheduled) → ✅ ancestor_inherited

When no row is written

A row is only written when it can change a subgroup:

Case Example Why no row
Group returns to the state subgroups already have reschedule_deletion after start_deletion on a deletion_scheduled group; cancel_transfer on an archived group Subgroups already match. A row would make the worker walk the whole subtree for nothing.
Group goes back to ancestor_inherited from an in-progress state with no saved state cancel_transfer from transfer_scheduled when nothing was saved Subgroups never took the in-progress state, so there is nothing to undo. The worker would log an error and drop the row.
Group enters an in-progress state start_deletion, schedule_transfer, start_transfer These states are never passed to subgroups.
Project namespace archiving a project It has no subgroups.
Feature flag off See below.

Other details

  • Gated by the namespace_state_propagation_outbox feature flag (gitlab_com_derisk, default off). It is checked against root_ancestor, so a whole hierarchy is enabled at once.
  • If a pending or processing row already exists for the same group and target, the insert does nothing and the transition still succeeds. The worker is still enqueued, and its deduplication handles repeats. The existing row keeps its original source_state.
  • exists? + create! was avoided because it is racy, and a RecordNotUnique would roll back the state change (this is what happened in the closed !247075 (closed)). create_or_find_by! was avoided because it uses subtransactions.
  • The callback writes to another table on purpose: the outbox pattern requires the row to be in the same transaction as the state change.

Database queries

INSERT INTO "namespace_state_propagations"
  ("namespace_id", "source_state", "target_state", "status", "created_at", "updated_at")
VALUES (<namespace_id>, 0, 1, 0, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
ON CONFLICT ("namespace_id", "target_state") WHERE (status = ANY (ARRAY[0, 1])) DO NOTHING
RETURNING "id"
Insert on public.namespace_state_propagations  (cost=0.00..0.02 rows=1 width=46) (actual time=0.780..0.782 rows=1 loops=1)
  Conflict Resolution: NOTHING
  Conflict Arbiter Indexes: idx_namespace_state_propagations_unique_pending_processing
  Buffers: shared hit=37 read=5 dirtied=12 written=6
  WAL: records=14 fpi=0 bytes=1228
  I/O Timings: read=0.143 write=0.088
  ->  Result  (cost=0.00..0.02 rows=1 width=46) (actual time=0.147..0.147 rows=1 loops=1)
        Buffers: shared hit=17 dirtied=1
Trigger RI_ConstraintTrigger_<redacted> for constraint fk_9798d3f752: time=21.015 calls=1

Known follow-ups (out of scope)

Overlapping state propagations for the same nam... (#635402 - closed)

References

Screenshots or screen recordings

Not applicable (backend only).

How to set up and validate locally

bin/rspec spec/models/concerns/namespaces/stateful_spec.rb \
  spec/services/namespaces/state_propagation_service_spec.rb \
  spec/workers/namespaces/state_propagation_worker_spec.rb

Or in a Rails console:

parent = Group.find(...)            # a group with at least one subgroup
child = parent.children.first
Feature.enable(:namespace_state_propagation_outbox, parent.root_ancestor)

parent.archive(transition_user: User.first)
Namespaces::StatePropagation.where(namespace_id: parent.id).last
# => pending row, source_state: "ancestor_inherited", target_state: "archived"

Namespaces::StatePropagationWorker.new.perform(parent.id, 'archived')
child.reload.state_name
# => :archived

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.

Edited by Shane Maglangit

Merge request reports

Loading
Loading