Posting & Drafts
Relevant source files
The following files were used as context for generating this wiki page:
Marginalia provides a local interface to manage GitLab merge request reviews through a two-stage process. Users first stage comments as private drafts and then publish them collectively as a single review. This system ensures that no automated content reaches GitLab without explicit user confirmation.
Sources: README.md:164-171, PRODUCT.md:31-36
Overview of the Posting Workflow
The posting system operates on an opt-in basis, requiring ALLOW_POSTING=true in the environment configuration. When enabled, the studio allows users to add bot-generated findings to a pending review.
- Staging: Users click "Add to review" on specific findings, creating GitLab draft notes.
- Management: Users view, edit, or delete individual drafts within the studio.
- Submission: Users publish all drafts at once, optionally adding a summary and a final verdict (Approve, Request Changes, or Comment).
Sources: README.md:204-213, studio/public/openapi.yaml:12-19
Data Flow for Review Submission
The following diagram illustrates the transition from local draft management to the final GitLab publication.
The studio acts as a management layer for GitLab's native draft_notes feature.
Sources: studio/public/openapi.yaml:138-147, studio/src/components/ConfirmSubmit.tsx:21-30
Draft Management
Drafts are stored on the GitLab server as draft notes, making them private to the token owner until publication. The studio synchronizes these drafts to provide a local management interface.
Draft Operations
The DraftRow component and associated API functions enable full CRUD operations on individual draft items before they are finalized.
| Operation | Action | API Endpoint |
|---|---|---|
| List | Fetches all pending drafts for an MR | GET /api/drafts/{slug} |
| Update | Modifies the body text of a specific draft | PUT /api/drafts/{slug}/{id} |
| Delete | Removes a draft note from GitLab | DELETE /api/drafts/{slug}/{id} |
Sources: studio/public/openapi.yaml:177-220, studio/src/components/DraftRow.tsx:10-40
Inline Anchoring
When adding a comment, the studio attempts to anchor it to a specific file and line. If GitLab refuses the anchor (e.g., the line is outside the current diff), the server falls back to creating a general note prefixed with the file path and line number.
Sources: studio/public/openapi.yaml:119-124, studio/src/lib/api.ts:140-145
Review Submission and Actions
Submitting a review triggers the draft_notes/bulk_publish GitLab endpoint. This process consolidates all drafts into a visible review and applies a final verdict.
Submission Parameters
The ConfirmSubmit component allows users to configure the final publication:
- Summary: An optional high-level overview of the review.
- Action: The final status applied to the Merge Request.
| Action | Description |
|---|---|
comment | Publishes drafts without changing the MR approval state. |
approve | Publishes drafts and approves the MR at the reviewed SHA. |
request_changes | Publishes drafts and marks the MR as "Work in Progress". |
Sources: studio/src/components/ConfirmSubmit.tsx:14-20, studio/public/openapi.yaml:143-147
Sequence of Submission
The server handles the multi-step process of publishing drafts and updating the MR state.
Sources: studio/public/openapi.yaml:138-175, studio/src/lib/api.ts:241-250
Triage Fixes
For MRs authored by the user, the bot identifies peer comments and can generate fixes. These are handled differently than standard review comments.
- Local Commits: Fixes are committed to a local branch
marginalia/<branch-slug>. - Pushing: If
ALLOW_PUSH=true, users can push these fixes to the remote MR branch via the studio. - Status Tracking: The studio tracks if local fixes are
ready(fast-forwardable),pushed, oroutdated.
Sources: README.md:105-116, studio/public/openapi.yaml:222-258, studio/src/lib/api.ts:312-332
Security and Constraints
- Host/Origin Protection: Write endpoints (
PUT,POST,DELETE) only accept requests from the studio itself to prevent DNS-rebinding and cross-site attacks. - Opt-in Requirement: All posting and pushing functionality remains disabled unless
ALLOW_POSTINGorALLOW_PUSHis explicitly set totrue. - Server-Side Resolution: The Merge Request identity is resolved server-side from
status.jsonusing the review slug, preventing clients from posting to arbitrary MRs.
Sources: studio/public/openapi.yaml:8-16, README.md:204-210
Conclusion
The Posting & Drafts system provides a safety buffer between bot-generated analysis and professional communication. By leveraging GitLab's draft notes, Marginalia allows developers to refine machine suggestions into human-validated reviews, maintaining the principle that the person always remains in control of external communication.