## Current status (2026-09-22): using GitHub OAuth, not GitHub App The Experiment now pursues a GitHub OAuth-based connection path instead of the GitHub App path the rest of this description was originally written around. The GitHub-App-specific work below isn't deleted — it's paused and moved to a dedicated sub-epic, [GitHub Sync - Experiment - GitHub APP](https://gitlab.com/groups/gitlab-org/-/work_items/23680), in case the App approach is revisited later. The scope, decisions, and phased plan below still describe the original GitHub App design as written; the issues remaining directly under this epic now target GitHub OAuth as the active path. --- ## What we want to achieve Moving a codebase from GitHub to GitLab is a big decision, and today's import tool assumes the customer has already made it. Many teams evaluating GitLab have not. They want a low-risk way to see their code, issues, and merge requests working in GitLab, and to keep that copy current while they evaluate, before committing to a move. The idea is a one-click way to bring a customer's GitHub repositories, issues, and pull requests into GitLab while GitHub stays the source of truth. GitLab keeps its copy current with one-way sync from GitHub, and the GitLab project stays read-only while sync is running, so nothing the team does on GitHub is lost or duplicated. When the customer is ready, they stop updates, the project becomes read-write, and sync cannot be turned back on. Until then they have a working, browsable, always-current copy of their project in GitLab. ## Experiment scope This Experiment phase is deliberately narrower than the full product vision above. It proves out sync reliability, the read-only-to-read-write cutover, and basic usage metrics, without committing to everything the eventual product needs. | In scope for the Experiment | Out of scope for the Experiment | |---|---| | Bulk GitHub org/repo connect and initial import (existing GitHub importer, reused as-is) | The GitHub-import landing page (a separate feature that lives only on the PoC branch and is not ported) | | GitHub OAuth authorization, with feedback on missing scopes | Writing changes from GitLab back to GitHub ("push-through") | | One-way continuous sync: branches/tags, LFS files, issues, pull requests (as merge requests), comments | Two-way sync of issues/MRs/comments back to GitHub | | Read-only enforcement of GitHub-derived content while sync is active | Automatic GitHub Actions → GitLab CI/CD conversion (workflow files still land as plain repo content) | | Sync status visibility, manual "update now," automatic repair of missed events, and a way to recover from lost access | PR reviews, review comments, approvals, reactions | | Irreversible "stop updates" cutover to ordinary read-write GitLab | A perfectly atomic cutover snapshot (a last-second GitHub change could be missed; accepted, not a defect) | | Basic usage metrics (sync-enabled projects, read-write switches) | Consumption billing and usage guardrails | | Turning off legacy pull/push mirroring while sync is active | Credential rotation (deferred to Beta; updates are a hard cutover for now) | | Detecting GitHub OAuth access revocation and letting the customer re-authorize | Landing on next-generation SCM (NG SCM); this runs on today's SCM stack | | Confirming CI/CD pipelines trigger on synced repository updates | Syncing changes made in GitLab back to GitHub after a cutover (manual today) | ## How the work is organized The underlying feature already exists as a working proof of concept: merge request [!251883](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/251883), `Draft: POC - Import GitHub repositories with continuous sync`, on branch `feature/github-connected-project-poc`. It's a real, largely complete implementation, about 40,000 lines of code, but it was never code-reviewed, and a real bug was already found in it (synced repository updates don't trigger CI/CD pipelines) that only surfaced because someone went looking for it. Merging that branch wholesale would repeat the same mistake at a much bigger scale. Instead, that MR will be closed and never merged. It stays around only as reference material. All of the actual work lands as a sequence of small, human-reviewable merge requests against `master`, each one built by reading the relevant part of the PoC and porting it over deliberately, fixing whatever review finds along the way. Every merge request lands behind the existing `github_continuous_import` feature flag (type `wip`, default off), so partial or incomplete work is always safe to merge. ## Decisions already made The following were settled by Product and engineering on 2026-09-09 unless noted otherwise: - **Naming:** the proof of concept's `Continuity::` namespace folds into the existing `Import` bounded context (decided 2026-09-09). The word itself changes to `Sync` (decided 2026-09-10): Ruby modules are `Import::Sync::...`, and tables are prefixed `import_sync_` (for example, `import_sync_repositories`). Tables are created with these final names from the start, so there's no later rename. - The Experiment runs on today's ("legacy") SCM stack, not next-generation SCM (NG SCM). - One instance-global GitHub App, installed by an instance administrator, is used for the whole Experiment. There is no per-customer GitHub App. - Read-only enforcement is sufficient at the policy/permissions layer alone; no additional model-level safeguard is required for this phase. - Credential rotation (being able to update a secret without a hard cutover) is deferred to Beta. For the Experiment, updating a credential means a hard cutover. - The `ExternalObject` model (which maps a GitHub object to its GitLab record) stays provider-agnostic, even though only GitHub is supported today. It is not being generalized any further right now. - **Fencing (decided 2026-09-10):** the proof of concept's PostgreSQL session-level advisory-lock barriers are not ported. They cannot work under PgBouncer transaction pooling, which GitLab requires. Concurrency control uses the Redis lease, row locks, and the `application_generation` counter instead; a paused worker writing a git ref moments after a cutover is an accepted, documented limitation. - **User mapping (2026-09-10):** improved user contribution mapping stays enabled for synced projects, and every record the sync creates or updates pushes placeholder references the same way the initial import does, so contributions can still be reassigned to real users later. - **Scope trimmed after an audit of the proof of concept (2026-09-10):** several PoC mechanisms are not ported because the Experiment does not need them or GitLab already has a conventional way to do the same thing. Not ported: the import-grant table and its two-phase prepare/consume flow (project creation resolves the App installation and authorizes inline, one request per repository); GitHub App user-token repository discovery (users sign in with the ordinary GitHub OAuth provider, and the App is used for installation tokens only); persisted webhook deliveries (webhooks are hints that bump a generation counter and enqueue a reconcile; lifecycle events enqueue the existing repair worker); the in-product "Reconnect" action (the 30-minute lifecycle repair restores access automatically); the resume state machine on the import page (after installing the App on GitHub the user returns to the import page and re-selects); and five write-only columns with their JSON schemas. Simplified: the install-callback state lives in the Rails session; the work-item cursor keeps its resumability but drops optimistic compare-and-swap; the repair cron uses `each_batch` fan-out; the settings panel uses the shared polling utility and confirm dialog; per-service error classes collapse into one module. Three generic fixes found in the PoC (LFS download hardening, the attachments-downloader retry cap, the open work item count cache) are filed as separate issues outside this epic. - **External object mapping keeps issue and merge request columns (2026-09-10):** even though the importer preserves GitHub numbers as GitLab iids today, a future two-way sync would break that matching, so the mapping table keeps `issue_id`, `merge_request_id`, and `note_id`. - **One connection per project (decided 2026-09-11):** the proof of concept kept one row per GitHub App installation in a connections table and pointed repositories at it. That table is not ported. Each synced project's row carries the installation it uses (installation ID, GitHub account, who connected it), so a project is self-contained. Installation-level changes such as a suspension update every project row on that installation together, and the repair cron makes one GitHub call per installation as before. As a consequence, one GitHub installation may serve projects in different GitLab organizations; the proof of concept prevented that only as a side effect of its schema, and nothing in one-way sync needs the restriction. - **Cells routing key (decided 2026-09-11):** the Beta design routes GitHub webhooks to the owning cell by the GitHub repository ID in the payload, claimed per synced project in the Topology Service. Installation-scoped events are not routed; the 30-minute repair on each cell picks them up. - **Offline simulator (decided 2026-09-10):** the proof of concept's GitHub simulator and its `test_mode` switch are not ported. Development uses a shared GitHub App; specs stub GitHub responses. - **Plan availability:** this feature is available to **GitLab Premium and Ultimate** users only. It is implemented in CE and gated using GitLab's existing licensed-feature mechanism. This resolves the open question on EE vs. CE placement. ## Open questions - **Resourcing trade-off (Import EM, P1):** dedicating two Import engineers to this work delays other committed Import roadmap items by two milestones. This trade-off needs explicit sign-off from Import leadership. - **Cutover states (Import engineering, P2):** should the `cutting_over` and `cutover_failed` states stay separate, or could they be simplified into one? Low urgency, cosmetic question.