Merge Passport by Orbit

A GitLab Duo workflow that uses Orbit context, Policy Packs, and CI to turn risky AI-generated merge requests into review passports before human approval.

Comment

🛂 Merge Passport by Orbit

Graph-backed merge review for AI-generated code

AI agents can generate code. GitLab Orbit gives that code permission to merge.

Merge Passport by Orbit is a GitLab Duo Agent Platform workflow that turns a Merge Request into a graph-backed review passport before humans approve risky AI-generated code.

It uses GitLab Orbit context, a configurable Policy Pack, a Context Safety Guard, GitLab CI, Duo Chat validation, and MR comment automation to help reviewers answer a critical question:

This code changed. But do we understand enough context to merge it?

🚨 The problem

AI coding agents are making software development faster than ever.

But merge review is becoming the new bottleneck.

A reviewer can usually see the diff, but they often cannot see the full context behind it:

  • Which downstream files may be impacted?
  • Is this touching billing, auth, security, permissions, or package dependencies?
  • Which tests should be required?
  • Is the team policy being followed?
  • Did the graph context succeed, fail, or return partial information?
  • Is the AI assistant creating false confidence?

The risk is not that AI writes code.

The risk is that teams merge AI-generated code without enough context.

💡 Inspiration

The project was inspired by a simple observation:

Modern AI agents are becoming very good at generating code, but the merge decision still depends on human trust.

Most review workflows answer:

“What changed?”

Merge Passport asks a deeper question:

“What context is required before this change should move forward?”

That is why the project is built around GitLab Orbit. A file diff alone is not enough. Reviewers need graph-backed context, policy signals, CI evidence, and a clear safety decision directly inside the GitLab workflow.

✅ What Merge Passport does

Merge Passport turns a GitLab Merge Request into a structured review passport.

For a given MR, it can:

  • Ingest live MR metadata from GitLab.
  • Capture the changed files.
  • Probe GitLab Orbit schema and tools.
  • Attempt graph-backed context retrieval.
  • Apply a configurable team Policy Pack.
  • Classify fallback risk when graph context is incomplete.
  • Generate a Passport Stamp.
  • Recommend required tests and reviewer guidance.
  • Produce MERGE_PASSPORT.md.
  • Produce a GitLab-ready MR_COMMENT.md.
  • Post a real review comment back into the MR.
  • Run a credential-free GitLab CI Passport Check.
  • Provide Duo Chat / Agent Platform validation guidance.
  • Generate an evidence pack for judges and reviewers.

🧠 The core idea

Merge Passport is not a generic chatbot.

It is a workflow designed for one specific moment in the software delivery lifecycle:

Before a risky Merge Request is approved.

The product combines four layers:

GitLab MR
  ↓
GitLab Orbit context attempt
  ↓
Team Policy Pack
  ↓
Context Safety Guard
  ↓
Merge Passport Stamp
  ↓
MR comment + CI artifact + Duo Chat explanation

🧩 Why GitLab Orbit matters

Code review should not rely only on local diffs.

A changed billing file may connect to pricing logic, invoices, revenue impact, tests, owners, and downstream services. A changed auth file may affect permissions, admin routes, and security assumptions.

GitLab Orbit is valuable because it gives the workflow a way to reason about codebase context as a graph.

In this project, Merge Passport probes Orbit schema and tools, attempts live graph context, and records the result honestly.

If Orbit graph traversal is incomplete or returns query_failed, Merge Passport does not fabricate confidence.

Instead, it activates the Context Safety Guard.

🛡️ Context Safety Guard

The Context Safety Guard is one of the most important parts of the project.

Merge Passport does not say:

“Looks good.”

when graph context is incomplete.

Instead, if a sensitive file is touched and Orbit context is partial or unavailable, it produces:

CONTEXT RISK DETECTED
Human review required

For example, the clean demo MR changes a billing discount fixture. Merge Passport detects:

Changed files captured: 1
Status: CONTEXT RISK DETECTED
Orbit context status: query_failed
Fallback patterns: billing, discount

That is the correct behavior.

The tool does not approve the MR. It does not merge the MR. It does not guarantee safety.

It gives reviewers the missing context before they make the decision.

🧾 Passport Stamp

Each run produces a concise Passport Stamp that summarizes the review state:

🛂 Merge Passport Stamp
- Live MR: verified
- Orbit schema/tools: verified
- Orbit graph query: query_failed
- Context Safety Guard: active
- Fallback risk: high
- Human review: required

This stamp is designed to be readable inside GitLab MR discussions, CI artifacts, and Duo Chat explanations.

⚙️ Policy Pack

Merge Passport includes a configurable merge-passport.policy.json.

This makes the system reusable across teams instead of hardcoded for one demo.

Example policy concepts:

{
  "highRiskPatterns": [
    "billing",
    "discount",
    "payment",
    "auth",
    "security",
    "jwt",
    "token",
    "package.json",
    "lockfile"
  ],
  "requiredTestsByPattern": {
    "billing": ["billing unit tests", "discount boundary tests"],
    "auth": ["permission regression tests", "security review"]
  },
  "reviewerGuidanceByPattern": {
    "billing": ["review discount edge cases and revenue impact"]
  }
}

A platform team can adapt this policy to its own risk model.

That means Merge Passport is not only a hackathon demo. It is a reusable review automation pattern for AI-assisted engineering teams.

🧪 Clean demo MR

The final demo uses a clean official GitLab Merge Request:

MR !2 — Clean billing discount change

It changes exactly one file:

fixtures/sample-app/src/billing/discounts.ts

The change modifies discount behavior by introducing an effective discount cap:

const effectiveDiscountPercent = Math.min(input.discountPercent, 80);

At first glance, this looks small.

But it touches billing logic.

Merge Passport correctly treats it as a sensitive change, probes GitLab Orbit, applies the Policy Pack, activates the Context Safety Guard, and posts a review passport back into the MR.

🏗️ Architecture

Developer opens MR
        ↓
Merge Passport CLI / Duo Skill
        ↓
Live GitLab MR ingestion
        ↓
GitLab Orbit probe + context attempt
        ↓
Policy Pack loader
        ↓
Risk classifier
        ↓
Context Safety Guard
        ↓
Passport renderer
        ↓
MR comment / CI artifact / Duo Chat explanation

Core components:

skills/merge-passport/SKILL.md
agent/merge-passport-agent.md
AGENTS.md
merge-passport.policy.json
src/core/policy-loader.ts
src/core/risk-classifier.ts
src/core/passport-generator.ts
src/core/passport-renderer.ts
src/cli/merge-passport.ts
src/cli/mr-comment.ts
.gitlab-ci.yml
docs/FINAL_EVIDENCE_PACK.md

🧑‍💻 How to use it

Credential-free local validation

npm install
npm run demo
npm run benchmark
npm run validate

Live GitLab MR workflow

npm run doctor
npm run orbit:probe
npm run orbit:context -- --mr 2
npm run passport -- --mr 2 --use-orbit
npm run mr:comment:dry-run
npm run mr:comment -- --mr 2 --post --yes

The live workflow requires authenticated GitLab CLI access and permissions for the official project.

🤖 GitLab Duo Chat validation

Merge Passport is also designed to be used through GitLab Duo Chat / Agent Platform.

The validated Duo Chat prompt asks the agent to inspect MR !2, explain what Merge Passport would do, mention the CLI command, apply the Context Safety Guard, and avoid claiming the MR is safe to merge.

Duo Chat correctly identified:

  • MR !2
  • the billing/discount file
  • the CLI workflow
  • the incomplete Orbit graph context
  • the Context Safety Guard
  • the requirement for human review

This proves the project is not only a CLI workflow. It is ready to operate as a Duo-native review assistant pattern.

🔁 GitLab CI Passport Check

The project includes a GitLab CI job:

merge-passport-check

The CI path runs credential-free validation:

npm ci
npm run demo
npm run benchmark
npm run validate

It stores review evidence artifacts such as:

  • MERGE_PASSPORT.md
  • MR_COMMENT.md
  • evidence/BENCHMARK_REPORT.md
  • evidence/raw/*.json
  • evidence/logs/*.log

This allows reviewers and judges to verify the workflow without needing live credentials.

📊 Evidence and benchmark

Merge Passport includes a benchmark comparing naive text context against graph-shaped context.

Benchmark result:

Cases: 5
Risk cases: 3
Naive missed risks: 2
Graph missed risks: 0
Context edges delta: 6
Risk signals delta: 4
Test recommendations delta: 6

The point is not to claim perfect safety.

The point is to show that graph-shaped context gives reviewers stronger signals than simple file matching alone.

Evidence files include:

  • evidence/BENCHMARK_REPORT.md
  • evidence/INDEX.md
  • docs/FINAL_EVIDENCE_PACK.md
  • docs/VALIDATION_MATRIX.md
  • screenshot evidence under docs/assets/

🧱 Built for GitLab Transcend

Merge Passport was built specifically for the GitLab Transcend Hackathon Showcase track.

It is designed as:

  • a reusable AI-native artifact,
  • a GitLab Duo Agent Platform skill / agent workflow,
  • a meaningful GitLab Orbit integration,
  • a concrete MR workflow automation,
  • a GitLab-native developer tool,
  • a reproducible project with evidence, CI, docs, and screenshots.

It is not just a chat demo.

It performs a specific software delivery workflow:

generate a graph-backed review passport before a risky MR is approved.

🧗 Challenges faced

The biggest challenge was handling live Orbit context honestly.

In the official environment, Orbit schema and tools were reachable, but graph traversal could return query_failed or partial results.

Instead of hiding this, the project turned it into a safety feature.

That led to the Context Safety Guard:

If the graph context is incomplete and the MR touches sensitive code, do not create false confidence. Require human review.

Another challenge was keeping the demo clean.

Early MR attempts included noisy generated evidence files. The final demo was rebuilt as a clean MR that changes exactly one billing discount file, making the story clear and judge-friendly.

📚 What I learned

This project reinforced several important lessons:

  1. AI code generation is only half of the workflow.
  2. Merge review needs context, not just summaries.
  3. Graph context is valuable, but systems must be honest when it is incomplete.
  4. A good AI workflow should know when not to be confident.
  5. The best developer tools meet engineers where they already work: in the MR, in CI, and in their assistant.

🚧 Limitations

Merge Passport is intentionally honest about its limits:

  • It does not approve merge requests.
  • It does not merge code.
  • It does not guarantee safety.
  • It does not fabricate Orbit graph results.
  • Live Orbit graph traversal may be partial or return query_failed.
  • The Policy Pack is a configurable guardrail, not proof of downstream impact.
  • Human reviewers remain responsible for final approval.

🔮 What is next

Future improvements could include:

  • publishing the workflow through the GitLab AI Catalog,
  • deeper Orbit graph query mapping,
  • CODEOWNERS-aware reviewer routing,
  • richer test recommendation generation,
  • multi-repo impact analysis,
  • policy templates for regulated teams,
  • stronger CI artifact visualization,
  • slash-command style workflows like:
/merge-passport mr 2
/merge-passport dry-run mr 2
/merge-passport post-comment mr 2 --confirm

🏁 Final takeaway

Merge Passport does not replace human reviewers.

It gives them the missing context before approving AI-generated code.

That is the future of merge review with GitLab Orbit.

Built With

  • ai
  • catalog
  • gitlab
  • gitlab-ci/cd
  • gitlab-cli
  • gitlab-duo-agent-platform
  • gitlab-duo-chat
  • gitlab-merge-requests-api
  • gitlab-orbit
  • json
  • markdown
  • mermaid-diagrams
  • node.js
  • playwright/browser-screenshot-automation
  • policy-pack-configuration
  • readiness
  • typescript
Share this project:

Updates