GitLab Poller

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• PRODUCT.md
• package.json
• studio/public/openapi.yaml
• studio/src/components/SettingsPage.tsx
• skills/marginalia-review/SKILL.md

The GitLab Poller is a local Node.js service that monitors GitLab merge requests (MRs). It automates the execution of AI-driven code reviews and triage tasks without requiring webhooks or public tunnels. The poller fetches MR data via the GitLab API and triggers headless Claude Code commands to process changes.

Sources: README.md:1-12, PRODUCT.md:19-24, package.json:4-6

Core Architecture and Execution Flow

The poller operates in a continuous loop, executing at a configurable interval. It maintains a dedicated Git worktree for the bot to ensure the developer's local working directory remains untouched.

Execution Cycle

The poller follows a specific sequence during each iteration:

1. Fetch open MRs for the configured project.
2. Filter MRs based on author, branch, and activity status.
3. Compare the current Head SHA with the last recorded state in state.json.
4. Trigger the appropriate command (REVIEW_COMMAND or TRIAGE_COMMAND) if changes are detected.
5. Collect and store reports as Markdown and JSON findings.

Sources: README.md:113-134, PRODUCT.md:38-44

Data Flow Diagram

The following diagram illustrates the relationship between the poller, GitLab, and the local AI processing environment.

Functional Workflows

The poller distinguishes between MRs authored by the user and those authored by teammates.

Code Review (Teammate MRs)

For MRs written by others, the poller runs the REVIEW_COMMAND. It analyzes the diff and generates a structured review.

• Trigger: New commits (Head SHA change).
• Environment: Detached HEAD or specific local branch in the bot worktree.
• Output: A Markdown report and a .marginalia-findings.json file.

Sources: README.md:136-148, skills/marginalia-review/SKILL.md:111-125

Comment Triage (User MRs)

For the user's own MRs, the poller monitors peer discussions.

• Trigger: New comments from reviewers.
• Action: Runs TRIAGE_COMMAND to analyze feedback and apply local fixes.
• Fix Persistence: Fixes are committed to a local marginalia/<branch-slug> branch but never pushed automatically.

Sources: README.md:151-180, PRODUCT.md:27-31

Configuration and State Management

The poller uses environment variables and JSON files to manage settings and track progress.

Primary Configuration

Option	File	Default	Description
POLL_INTERVAL_MINUTES	.env / settings.json	5	Time between poll cycles.
STALE_AFTER_DAYS	.env / settings.json	14	Days of inactivity before skipping an MR.
ALLOWED_TARGET_BRANCHES	.env / settings.json	All	Filter for specific target branches.
GITLAB_TOKEN	.env	N/A	Token with api scope.

Sources: README.md:68-80, studio/src/components/SettingsPage.tsx:16-21, studio/public/openapi.yaml:370-376

State Tracking

The poller relies on local files to maintain persistence across restarts:

• state.json: Records the last reviewed SHA and triage timestamps.
• status.json: Exports the live status of the bot (e.g., polling, reviewing, idle) for the SwiftBar icon and Studio UI.
• posted.json: Tracks comments already sent to GitLab to prevent duplicates.

Sources: README.md:144-148, README.md:267-270, studio/public/openapi.yaml:500-530

Bot Worktree Management

The poller creates and manages a dedicated Git worktree to isolate its operations.

1. Initialization: On first run, it creates the BOT_WORKTREE_DIR.
2. Symlink: It creates a symlink to the real checkout's .claude directory to access custom commands.
3. Cleaning: Before each run, it executes git clean -fdx and git reset --hard.
4. Checkout: It checks out the specific MR branch. If BOT_CHECKOUT=detached is set, it avoids moving existing local branches.

Sources: README.md:92-101

Sequence of a Single Review

The following sequence diagram shows the interaction between the poller and the AI execution layer during a review task.

The GitLab Poller acts as the bridge between GitLab's collaborative environment and local AI-assisted development tools. It ensures that reviews and triages stay up-to-date with minimal manual intervention while keeping the developer in control of final pushes and postings via the Marginalia Studio.

Sources: PRODUCT.md:33-36, README.md:227-235