Microfrontend Platform

Summary

GitLab ships as a monolith behind a single domain (gitlab.company.com). Product surfaces such as Duo Chat or Work Items are tightly coupled to the monolith build and release cycle. This design document proposes a micro-frontend (MFE) platform that lets product surfaces be developed, built, versioned, and deployed independently while remaining invisible to the end user: everything stays behind one domain and one login.

Motivation

Problems

• Monolith coupling. Every frontend change, no matter how small, requires a full monolith release. A one-line fix to Duo Chat waits for the same pipeline as a database migration.
• Team coupling. All teams share one Webpack config, one dependency tree, and one CI pipeline. A broken lint check in one area blocks every deployment.
• No independent versioning. There is no mechanism to upgrade or downgrade a single product surface. Rollback means rolling back the entire monolith.
• External modules have no UI path. LabBench modules (separately deployed services) have no standard way to inject UI into the GitLab shell. Each module invents its own integration.

Goals

1. Product teams can deploy a UI change to their surface without a monolith release.
2. Multiple versions of an MFE can coexist. Upgrade and downgrade are version picks.
3. Self-managed and air-gapped installs receive MFEs through the same release channel they already use.

Non-Goals

• Single-domain routing (GATE). The routing layer that puts modules behind one domain is owned by the GATE project and has its own timeline. Until GATE is available, the monolith is configured with the marketplace URL and that origin is added to the CSP.
• Module discovery. The monolith cannot yet discover which LabBench modules are deployed. The marketplace location is monolith configuration for now.
• Migrating specific product surfaces. Each surface remains a consumer of the platform and is tracked with its owning team. This document covers the platform, not the migrations.

Constraints today

• No single domain yet. Until GATE delivers routing for all deployment types (Omnibus through Kubernetes), the monolith is configured with the marketplace URL and that origin is added to the CSP so MFEs can be embedded from it.
• No module discovery. The monolith cannot discover which modules are deployed. The marketplace location is monolith configuration, and the manifest must work without discovery.

Decisions

• ADR 001: Tooling repository strategy - Monorepo for tightly coupled tooling, polyrepo for standalone utilities. Also captures the open question of where MFE application code lives.

Prior art and existing work

• Architecture RFC (Rafa Frederico, 2026-04-23): validates Module Federation 2.0 runtime integration with the Webpack 4 host, the mount/unmount ABI, and same-origin serving.
• Architecture counter-RFC (Illya Klymov, 2026-07-12): proposes versioned and integrity-verified delivery, layered contract ownership, rspack as the build tool, and registry-first phasing. Accompanied by a working implementation (!245014).
• Frontend Decomposition design document: covers the monolith-side modularization that MFEs consume from outside.
• MFE registry: existing prototype for publishing MFE assets to GCS with SHA256 checksums and version manifests.

Alternative solutions

Do nothing

Product surfaces remain coupled to the monolith release cycle. Teams cannot deploy independently. External modules have no standard UI path. Vue 3 adoption is blocked on a monolith-wide migration.

Pros: No new infrastructure to build or operate.

Cons: Coupling cost grows with the number of teams and surfaces.

iframes

Each surface is loaded in an iframe pointed at the module’s own domain.

Pros: Strong isolation. No shared JavaScript scope. Cons: Poor UX (no shared navigation, double scrollbars, no shared authentication without postMessage). Accessibility and performance penalties. Does not meet the “one domain” requirement.

Build-time integration (npm packages)

Each surface is published as an npm package and compiled into the monolith Webpack build.

Pros: No runtime federation overhead. Single build graph. Cons: Does not solve independent deployment or rollback. Every surface change still requires a monolith release. Does not help external modules.

View page source - Edit this page - please contribute.