Introduce a feature flag for Repository in Vue3 mode
What does this MR do and why?
This MR migrates GitLab's repository views (tree, blob, project overview) to Vue 3 behind the vue3_migrate_repository feature flag, with comprehensive error handling and automatic Vue 2 fallback.
Problem
The repository views are critical user-facing features that require careful migration to Vue 3. This migration needed to:
- Support both Vue 2 and Vue 3 simultaneously during the rollout period
- Handle architectural differences between Vue 2 and Vue 3 (router, Vuex, Apollo)
- Fix Vue 3-specific compatibility issues (reactivity, watchers, prop validation)
- Ensure zero downtime if Vue 3 fails to load or has runtime errors
Solution
- Feature Flag Infrastructure
- Created
vue3_migrate_repositorybeta feature flag (milestone 18.11) - Exposed flag to frontend via gon.features in relevant controllers:
ApplicationController(global)Projects::BlobController(file viewing)Projects::TreeController(directory browsing)ProjectsController(project overview)
Error Resilience with Vue 2 Fallback
Implemented comprehensive error handling across 9 Vue 3 initialization points:
if (gon.features?.vue3MigrateRepository) {
(async () => {
try {
// Try Vue 3
const { default: initComponent } = await import('~/component?vue3');
initComponent();
return;
} catch (e) {
Sentry.captureException(e);
}
// Automatically fall back to Vue 2
initVue2Component();
})();
} else {
// Vue 2 (feature flag disabled)
initVue2Component();
}References
- [FF] repository_vue3_compat_mode - rendering Re... (#588786)
- Add ?vue3 infection plugin for iterative Vue 3 ... (!226978 - merged)
- Refactor Blob initalisation (!230120 - merged)
- Introduce vue3_migrate_admin_runners to migrate... (!227100 - merged)
- Make sure Pinia is not accessed when not init o... (!231166 - merged)
Screenshots or screen recordings
| Context | Before | After |
|---|---|---|
| Project overview | ![]() |
![]() |
| Repository - tree | ![]() |
![]() |
| Repository - tree |
![]() |
![]() |
| Repository - blob | ![]() |
![]() |
How to set up and validate locally
- Enable the Vue 3 migration feature flag in Rails console:
Feature.enable(:vue3_migrate_repository) - Test 1: Tree View (Repository Root)
- Navigate to a project's repository root:
http://127.0.0.1:3000/<namespace>/<project>/-/tree/<branch> - Verify: File tree loads correctly with folders and files displayed
- Verify: Breadcrumbs show the correct project name (not empty or just a space)
- Verify: Click through folders - navigation works smoothly
- Verify: Last commit information displays for each file/folder
- Verify: No Vue warnings in browser console (except known Vue Devtools warning)
- Test 3: Project Show Page (README view)
- Navigate to the project overview page:
http://127.0.0.1:3000/<namespace>/<project> - Verify: README renders correctly if present
- Verify: File tree browser appears if README is present
- Verify: Code dropdown button works for cloning options
- Test 2: Blob View (File Viewing)
- Click on any file in the repository to view its contents
- Verify: File content displays correctly with syntax highlighting
- Verify: Breadcrumbs show full path from project root to current file
- Verify: "History" button works and links to commit history
- Verify: File actions (Edit, Delete, etc.) are available in the header
- Verify: Table of contents appears for supported file types (Markdown, etc.)
❗ Reload the file page and repeat steps for Test 2 with the blob initialised not from the tree.
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.
Related to #588786
Edited by Paulina Sedlak-Jakubowska







