Stacked MRs Support
Relevant source files
The following files were used as context for generating this wiki page:
Stacked MRs Support manages a sequence of dependent Merge Requests (MRs) where the target branch of one MR serves as the source branch for another. The Marginalia bot identifies these relationships during its polling cycle and treats the collection of MRs as a unified stack. This support ensures that the AI reviewer understands the context of the entire chain, preventing redundant findings for issues that later layers resolve.
Sources: README.md:144-145, studio/src/lib/api.ts:133-137
Architecture and Discovery
The bot rebuilds the stack structure from the list of open MRs on every poll. It identifies a "layer" when it detects an MR whose target branch matches the source branch of another open MR. The system checks ALLOWED_TARGET_BRANCHES against the base branch of the entire stack, ensuring upper layers remain included even if their immediate target branch is not the base branch.
Sources: README.md:144-149
Data Flow for Stack Processing
The following diagram illustrates how the bot identifies and processes a stack of MRs.
The bot fetches layers locally using the reference format refs/marginalia/stack/<iid>. Reviews proceed in a strict bottom-to-top order. Each review run receives the full stack context, including the layer list and existing reviews of other layers.
Sources: README.md:150-154
Review Logic and Cross-Layer Findings
Stacked reviews include a specialized ### Across layers section in the final report. This section uses specific markers to indicate how a finding relates to the broader stack. The AI reviewer uses the local stack references to determine if a bug in a lower layer is settled by a commit in a higher layer.
Sources: README.md:154-156, studio/src/lib/api.ts:121-125
Cross-Layer Finding Types
| Kind | Description |
|---|---|
settled-later | A finding identified in a lower layer that is addressed in a subsequent layer of the stack. |
belongs-lower | Logic or changes in a higher layer that should have been implemented in a base layer. |
assumes-upper | Code that relies on changes not yet merged in the layers above. |
Sources: studio/src/lib/api.ts:122-124, studio/public/openapi.yaml:410-415
State Management and Re-reviews
The bot maintains stack state in state.json. A layer is automatically flagged for re-review if the layer directly beneath it receives new commits. This ensures the reviewer accounts for changes in the dependency chain.
Sources: README.md:157-158
API Representation
The Studio API provides structured data for visualizing stacks through the Stack and StackLayer schemas.
Studio Integration
The Marginalia Studio displays the stack as a "merge board" above the detailed review. This board provides a visual representation of the hierarchy and the status of each layer. Layers authored by the user are excluded from this board and are instead processed through the triage flow.
Sources: README.md:159-160, DESIGN.md:214-220
Visualizing Stack Relationships
The relationship between MRs in a stack is strictly hierarchical, as shown in this ER diagram.
A StackLayer refers to its parentIid to maintain the chain. The status field tracks whether a layer is pending, reviewing, failed, skipped, or up_to_date.
Sources: studio/src/lib/api.ts:133-142, studio/public/openapi.yaml:482-487
Summary
Stacked MRs Support enables the Marginalia bot to perform context-aware reviews on interdependent changes. By rebuilding the stack hierarchy on every poll and reviewing from the bottom up, the system identifies cross-layer dependencies and avoids redundant reporting. The local reference fetching and specialized markdown sections allow the AI to communicate complex relationships between different MRs within the same development stream.