## Why The GitHub continuous sync feature already exists as a working proof of concept in merge request [!251883](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/251883) (`Draft: POC - Import GitHub repositories with continuous sync`, branch `feature/github-connected-project-poc`). That MR is about 40,000 lines and was never code-reviewed, and a real bug was already found in it that a full review would likely have caught. Rather than merge it as-is, we're closing that MR for good and porting its pieces into `master` as a series of small merge requests that reviewers can actually read. This issue is the first piece of application code: the database tables and the ActiveRecord models on top of them. Everything here lands behind the existing `github_continuous_import` feature flag (type `wip`, default off, created in the prerequisite issue this one depends on), so it has no effect on any real project until later work turns it on. A scope audit on 2026-09-10 dropped two of the PoC's tables from the port entirely: `webhook_deliveries` and `import_grants`. Webhooks move to a hint-then-verify design that never needs a durable delivery row (see https://gitlab.com/gitlab-org/gitlab/-/work_items/628589), and initial import provisioning drops the short-lived grant credential in favor of resolving and authorizing each request directly (see https://gitlab.com/gitlab-org/gitlab/-/work_items/628586). A further decision on 2026-09-11 drops the `connections` table too: the installation fields it held move onto `repositories` itself, so each synced project is self-contained instead of pointing at a shared connection row (see "Why no connections table" in the Table structure section below). So this issue now lands three tables and three models, not six. ## What to do Read the three model files in the PoC and the migrations that built their tables, then port them into a fresh MR against `master`, using the final names (the fold into `Import` was decided 2026-09-09, the word `Sync` on 2026-09-10): - Ruby modules: `Import::Sync::*` (not `Continuity::*`) - Tables: prefixed `import_sync_` (for example, `import_sync_repositories`, not `continuity_repositories`) - One table drops a now-doubled word: `continuity_repository_sync_states` becomes `import_sync_repository_states`, and the model becomes `Import::Sync::RepositoryState` **No `import_sync_webhook_deliveries` or `import_sync_import_grants` table.** The PoC's `continuity_webhook_deliveries` and `continuity_import_grants` are dropped from the port entirely, not squashed or renamed. Do not create either table or model. **No `import_sync_connections` table either.** The PoC's `continuity_connections` is dropped from the port too (decided 2026-09-11): the installation fields it held (`provider`, `provider_installation_id`, `provider_account_id`, `provider_account_login`) move onto `import_sync_repositories`, along with `connected_by_user_id` replacing the connection's `installed_by_user_id`. The connection's `namespace_id`, `state` enum, and `last_inventory_at` are dropped outright: the project already has a namespace, and the repository's `authority_state` plus `disconnect_reason` already say why access was lost. Do not create either table or model. **Migrations.** The PoC has 30 migrations because columns, indexes, and constraints were added incrementally over time, across all six of its tables. Of those 30, drop the following outright rather than squashing them: - `20260824120014` (the `test_mode` column) and `20260824120021` (the fixture-account index), see below. - The six migrations that build `continuity_import_grants`: `20260824120016`, `20260824120017`, `20260824120018`, `20260824120019`, `20260824120020`, `20260824120028`. - The five migrations that build `continuity_webhook_deliveries`: `20260824120003`, `20260824120012`, `20260824120013`, `20260824120015`, `20260824120025`. - `20260825080000` is ported, but only its `continuity_repositories` half (the `disconnect_reason` and `restore_authority_state` columns, their check constraints, and the provider-bound partial unique index). Drop the part of that migration that adds `lifecycle_metadata` to `continuity_webhook_deliveries`; that table isn't ported. Also drop the six migrations that build `continuity_connections` outright, since that table isn't ported either (decided 2026-09-11): `20260824120000`, `20260824120004`, `20260824120005`, `20260824120006`, and the same `20260824120014`/`20260824120021` already dropped above for the `test_mode` column and fixture-account index (now the whole table goes with them). `20260824120008` (`add_continuity_repositories_connection_fk`) is not ported either, for a different reason: there's no `connections` table left to add the foreign key to. The columns that migration would have pointed at (`provider`, `provider_installation_id`, `provider_account_id`, `provider_account_login`) go straight into the `repositories` create-table migration instead, per the Table structure section below. That leaves the migrations for the three remaining tables (repositories, repository_states, external_objects). Since none of this has shipped anywhere, squash each table's follow-up migrations into one `create_table` migration per table, so you end up with three migrations instead of the remainder of the 30. If a foreign key needs to be added outside a DDL transaction per GitLab's migration style guide, it can stay in its own migration; use your judgment, the goal is as few migrations as correctness allows. Set the migration `milestone` to whatever milestone is current when you merge, not the PoC's `19.3`. All three tables are `gitlab_main_org`, sharded by `organization_id`, same as in the PoC. Keep the PoC's check constraints, partial unique indexes, and foreign keys unless the database reviewer asks you to change something. **One deliberate change: `continuity_external_objects` becomes `import_sync_external_objects`, with a different shape.** The PoC identifies the local GitLab record with a polymorphic pair, `local_record_type` (text) plus `local_record_id`. GitLab's database guidelines (`doc/development/database/polymorphic_associations.md`) say to avoid this pattern because it can't have a real foreign key. Replace it with three nullable columns instead: `issue_id`, `merge_request_id`, `note_id`, each with its own `ON DELETE CASCADE` foreign key. Add a check constraint that exactly one of the three is set, and a partial unique index per column, scoped to the repository, to preserve the PoC's "one mapping per local record" guarantee. The `timelogs` table already uses this exact shape (nullable `issue_id`, `merge_request_id`, `note_id` with real foreign keys) as precedent. Keep the `kind` enum for the GitHub side of the mapping, but drop the `review` (3) and `review_comment` (4) values, since PR reviews and review comments are out of scope for this Experiment. Update the `ExternalObject` model to match: `local_record` should return whichever of the three columns is set, and `record!` should write to the column matching the record's base class, instead of setting `local_record_type`/`local_record_id`. **Second deliberate change: drop the `test_mode` column and the fixture-account index from `connections`.** In the PoC, `test_mode` marks a connection as belonging to an offline GitHub simulator used for GDK development, and migration `20260824120021` adds a partial unique index for those fixture accounts. The simulator is not being ported at all (decided 2026-09-10), so neither the column nor the index has a purpose; they'd be dropped even if `connections` were still a table in its own right, which it no longer is (see above). Do not port them. Specs use the usual GitHub importer approach instead: stubbed HTTP responses and local git fixtures. **Enum columns and their check constraints.** Every integer enum column gets a check constraint that allows exactly the enum's values, nothing more. The PoC already does this; keep it when squashing, and narrow the `kind` row as noted: | Table (final name) | Column | Allowed values | |---|---|---| | `import_sync_repositories` | `provider` | `0` (github) | | `import_sync_repositories` | `authority_state` | `0..6` (provisioning, bootstrap_canceled, provider_canonical, disconnected, cutting_over, cutover_failed, gitlab_canonical) | | `import_sync_repositories` | `disconnect_reason` | `NULL` or `0..3` | | `import_sync_repositories` | `restore_authority_state` | `NULL`, `0`, or `2` (only provisioning and provider_canonical are valid restore targets) | | `import_sync_repository_states` | `domain` | `0..2` (inventory, source, work_items) | | `import_sync_repository_states` | `state` | `0..6` (pending, running, current, delayed, degraded, paused, disconnected) | | `import_sync_external_objects` | `kind` | `0..2` (issue, pull_request, issue_comment); the PoC allows `0..4`, narrow it after dropping the review kinds | Port the three models with their associations, enums, validations, cross-organization guards, scopes, and pure read-only predicate methods (things like `read_only?`, `provider_bound?`, `lagging?`). Port their specs and factories too. Do not port services, workers, controllers, or the test-provider adapter; those belong to later issues. **Also port the associations the PoC adds to core models,** so later LAND issues have something to call instead of each inventing the naming. In `app/models/project.rb`, port the `has_one` the PoC adds: ```ruby has_one :import_sync_repository, class_name: 'Import::Sync::Repository', inverse_of: :project, autosave: true ``` (the PoC names it `continuity_repository`/`Continuity::Repository`; rename both.) Read the diff with `git -C /Users/rodrigotomonari/gdk/gitlab diff origin/master...HEAD -- app/models/project.rb` before touching this file: port only this `has_one`, not the rest of that diff (`update_remote_mirrors`'s `WritePolicy` check and the `complete_after_import` extraction belong to https://gitlab.com/gitlab-org/gitlab/-/work_items/628587). `app/models/user.rb` needs no change in this issue. The PoC adds two `has_many` associations here, `installed_continuity_connections` and `continuity_import_grants`; neither is ported. `installed_continuity_connections` pointed at the now-dropped `Connection` model (decided 2026-09-11): the installation fields it exposed live on `Import::Sync::Repository` instead, and there's no per-user list of installations left to expose from `User`. `continuity_import_grants` has no model to point at either, since `ImportGrant` is dropped (see https://gitlab.com/gitlab-org/gitlab/-/work_items/628586). ## Table structure This is the target shape after squashing, with the decisions in this issue applied. Every table is `gitlab_schema: gitlab_main_org` with `organization_id` as its sharding key, has a `bigint` primary key `id`, and has `created_at` and `updated_at` as `timestamp with time zone NOT NULL`. Column order within a table does not matter; names, types, nullability, defaults, indexes, and constraints do. Text columns carry the length check GitLab requires. Compare the squashed migrations against this, not against the PoC. There is no connections table. The PoC kept one row per GitHub App installation in `continuity_connections` and pointed repositories at it. That table is not ported (decided 2026-09-11): the installation fields live on the repository row instead, so each synced project is self-contained. See "Why no connections table" below. ### `import_sync_repositories` One row per GitLab project kept updated from a GitHub repository. Unique per project. Carries the GitHub App installation that grants access to the repository. | Column | Type | Null | Default | Notes | |---|---|---|---|---| | `organization_id` | bigint | no | | FK `organizations(id)` ON DELETE CASCADE | | `project_id` | bigint | no | | FK `projects(id)` ON DELETE CASCADE | | `connected_by_user_id` | bigint | yes | | FK `users(id)` ON DELETE SET NULL; who started the connected import (PoC: `installed_by_user_id` on connections) | | `authority_state` | smallint | no | 0 | enum, see the enum table | | `disconnect_reason` | smallint | yes | | enum, see the enum table | | `restore_authority_state` | smallint | yes | | enum, see the enum table | | `application_generation` | bigint | no | 0 | the fence every write compares against | | `provider` | smallint | no | 0 | enum, only `github` (0) (PoC: on connections) | | `provider_installation_id` | bigint | no | | GitHub App installation ID used to mint tokens (PoC: on connections) | | `provider_account_id` | bigint | no | | GitHub account (org or user) that owns the installation (PoC: on connections) | | `provider_account_login` | text | no | | length <= 255 (PoC: on connections) | | `provider_repository_id` | bigint | no | | GitHub repository ID | | `provider_repository_node_id` | text | no | | length <= 255 | | `provider_full_name` | text | no | | `owner/name`, length <= 255 | | `provider_default_branch` | text | yes | | length <= 255 | | `cutover_requested_at` | timestamptz | yes | | | | `cutover_completed_at` | timestamptz | yes | | | Indexes: `organization_id`; `connected_by_user_id`; `provider_installation_id` (the lifecycle handlers and the repair cron fan out over every repository of one installation); unique `project_id`; partial unique `(organization_id, provider_repository_id) WHERE authority_state IN (0, 2, 3, 4, 5)`. The `WHERE` lists the provider-bound states, so a GitHub repository can be connected again after a cutover or a canceled bootstrap but never twice at once in the same organization. Checks: `provider = 0`; `authority_state BETWEEN 0 AND 6`; `disconnect_reason IS NULL OR disconnect_reason BETWEEN 0 AND 3`; `restore_authority_state IS NULL OR restore_authority_state IN (0, 2)`; `application_generation >= 0`; `provider_installation_id > 0`; `provider_account_id > 0`; `provider_repository_id > 0`. Not ported from the PoC: `continuity_connection_id` and its index and FK; the partial unique index `(continuity_connection_id, provider_repository_id)`; the `cutover_domain_boundaries` jsonb column and its JSON schema (write-only). ### `import_sync_repository_states` One row per repository per sync domain (`inventory`, `source`, `work_items`): the generation counters and health for that domain. PoC name: `continuity_repository_sync_states`. | Column | Type | Null | Default | Notes | |---|---|---|---|---| | `organization_id` | bigint | no | | FK `organizations(id)` ON DELETE CASCADE | | `import_sync_repository_id` | bigint | no | | FK `import_sync_repositories(id)` ON DELETE CASCADE (PoC: `continuity_repository_id`) | | `domain` | smallint | no | | enum `inventory` 0, `source` 1, `work_items` 2 | | `state` | smallint | no | 0 | enum, see the enum table | | `desired_generation` | bigint | no | 0 | bumped by every hint (webhook, cron, "Update now") | | `synced_generation` | bigint | no | 0 | advanced only after a whole pass succeeds | | `cursor` | text | yes | | resumable paging position, length <= 2048 | | `last_error_code` | text | yes | | length <= 255 | | `last_error_message` | text | yes | | length <= 1024, already sanitized | | `bootstrap_started_at` | timestamptz | yes | | | | `last_event_at` | timestamptz | yes | | | | `last_sync_started_at` | timestamptz | yes | | | | `last_successful_sync_at` | timestamptz | yes | | | Indexes: `organization_id`; `import_sync_repository_id`; unique `(import_sync_repository_id, domain)`. Checks: `domain BETWEEN 0 AND 2`; `state BETWEEN 0 AND 6`; `desired_generation >= 0`; `synced_generation >= 0`; `synced_generation <= desired_generation` (the fencing invariant). ### `import_sync_external_objects` One row per GitHub object mapped to the GitLab record it produced. This is the table whose shape changes most from the PoC: the polymorphic `local_record_type`/`local_record_id` pair becomes three nullable foreign keys. | Column | Type | Null | Default | Notes | |---|---|---|---|---| | `organization_id` | bigint | no | | FK `organizations(id)` ON DELETE CASCADE | | `import_sync_repository_id` | bigint | no | | FK `import_sync_repositories(id)` ON DELETE CASCADE (PoC: `continuity_repository_id`) | | `kind` | smallint | no | | enum `issue` 0, `pull_request` 1, `issue_comment` 2 | | `provider_object_id` | bigint | no | | GitHub object ID | | `provider_updated_at` | timestamptz | yes | | | | `issue_id` | bigint | yes | | FK `issues(id)` ON DELETE CASCADE | | `merge_request_id` | bigint | yes | | FK `merge_requests(id)` ON DELETE CASCADE | | `note_id` | bigint | yes | | FK `notes(id)` ON DELETE CASCADE | Indexes: `organization_id`; `import_sync_repository_id`; unique `(import_sync_repository_id, kind, provider_object_id)`; partial unique `issue_id WHERE issue_id IS NOT NULL`; partial unique `merge_request_id WHERE merge_request_id IS NOT NULL`; partial unique `note_id WHERE note_id IS NOT NULL`. The three partial unique indexes replace the PoC's `(repository, local_record_type, local_record_id)` index: a GitLab record can be mapped once, and each foreign key column has the index GitLab requires for cascading deletes. Checks: `kind BETWEEN 0 AND 2`; `provider_object_id > 0`; exactly one of `issue_id`, `merge_request_id`, `note_id` is set, written as `num_nonnulls(issue_id, merge_request_id, note_id) = 1`. Not ported from the PoC: `local_record_type`, `local_record_id`, their two indexes, the `fingerprint` column (write-only), and the `review` (3) and `review_comment` (4) values of `kind`. ### Why no connections table The PoC's connection row existed for three reasons, and each is covered without it. Token minting needs the installation ID, which is now on the repository row and can be cached per installation. Installation lifecycle changes (suspended, removed, repositories removed) now update every repository row with that `provider_installation_id` in one transaction; the repository's `authority_state` and `disconnect_reason` already express the result, so the connection-level `state` enum had no job left. The repair cron groups repositories by `provider_installation_id` and makes one GitHub call per installation, the same call count as before. The one thing the connection table enforced as a side effect, "one GitHub installation belongs to one GitLab organization," is deliberately not kept: nothing in one-way sync needs it, and two teams sharing a GitHub organization may use separate GitLab organizations. ## PoC files to read Models (in `app/models/continuity/`, to become `app/models/import/sync/`): - `repository.rb` - `repository_sync_state.rb` - `external_object.rb` (needs the polymorphic-to-foreign-key change described above) Do not read or port `connection.rb`, `webhook_delivery.rb`, or `import_grant.rb`; none of these three tables is part of this port. Read `connection.rb` only far enough to see the validations and format of the installation fields (`provider`, `provider_installation_id`, `provider_account_id`, `provider_account_login`) that move onto `repository.rb`, not as a model to port. Specs and factories: `spec/models/continuity/` and `spec/factories/continuity/`, for the three models above only. Diffs only (not full files): `app/models/project.rb` (the `has_one :continuity_repository` line only). Get the diff with `git -C /Users/rodrigotomonari/gdk/gitlab diff origin/master...HEAD -- app/models/project.rb`. `app/models/user.rb` needs no change in this issue (see above), so there's no diff to read for it. Migrations (`db/migrate/`), 30 files in the PoC, of which the three tables in this issue account for 11 (the rest build `continuity_connections`, `continuity_webhook_deliveries`, and `continuity_import_grants`, dropped below). Consolidate those 11 into three `create_table` migrations, one per table, plus `20260825080000`'s `continuity_repositories` half folded into the `repositories` migration. Dropped rather than squashed: the six `continuity_connections` migrations (`20260824120000`, `20260824120004`, `20260824120005`, `20260824120006`, `20260824120014`, `20260824120021`), `20260824120008` (the repositories-to-connections foreign key, no longer needed), the six `continuity_import_grants` migrations (`20260824120016`-`20260824120020`, `20260824120028`), and the five `continuity_webhook_deliveries` migrations (`20260824120003`, `20260824120012`, `20260824120013`, `20260824120015`, `20260824120025`). The `lifecycle_metadata` column that `20260825080000` adds to `continuity_webhook_deliveries` is dropped along with that table; only the migration's `continuity_repositories` columns are ported. Squash into the `repositories` migration: - `20260824120001_create_continuity_repositories.rb` - `20260824120007_add_continuity_repositories_organization_fk.rb` - `20260824120009_add_continuity_repositories_project_fk.rb` - `20260825080000_add_github_lifecycle_state_to_continuity_records.rb`, only its `continuity_repositories` columns (`disconnect_reason`, `restore_authority_state`), their check constraints, and the provider-bound partial unique index. Its `continuity_webhook_deliveries` column is dropped. The `repositories` create-table migration also needs to add the installation columns and index directly (`provider`, `provider_installation_id`, `provider_account_id`, `provider_account_login`, and the index on `provider_installation_id`), since there's no `connections` table to read them from. See the Table structure section above for the exact shape. Squash into the `repository_states` migration: - `20260824120002_create_continuity_repository_sync_states.rb` - `20260824120010_add_continuity_repository_sync_states_organization_fk.rb` - `20260824120011_add_continuity_repository_sync_states_repository_fk.rb` Squash into the `external_objects` migration: - `20260824120022_create_continuity_external_objects.rb` - `20260824120023_add_continuity_external_objects_organization_fk.rb` - `20260824120024_add_continuity_external_objects_repository_fk.rb` - `20260824120026_add_unique_local_identity_to_continuity_external_objects.rb` - `20260824120027_release_retired_continuity_repository_identity.rb` Drop entirely, because `continuity_connections` isn't ported (decided 2026-09-11): - `20260824120000_create_continuity_connections.rb` - `20260824120004_add_continuity_connections_organization_fk.rb` - `20260824120005_add_continuity_connections_namespace_fk.rb` - `20260824120006_add_continuity_connections_installed_by_user_fk.rb` - `20260824120014_add_test_mode_to_continuity_connections.rb` - `20260824120021_add_unique_fixture_account_index_to_continuity_connections.rb` - `20260824120008_add_continuity_repositories_connection_fk.rb`, for a different reason: there's no `connections` table left to add this foreign key to. Drop entirely, not squashed, because their table isn't ported: - `20260824120003_create_continuity_webhook_deliveries.rb` - `20260824120012_add_continuity_webhook_deliveries_organization_fk.rb` - `20260824120013_add_continuity_webhook_deliveries_connection_fk.rb` - `20260824120015_add_continuity_webhook_delivery_digest_constraint.rb` - `20260824120025_add_scheduled_generation_to_continuity_webhook_deliveries.rb` - `20260824120016_create_continuity_import_grants.rb` - `20260824120017_add_continuity_import_grants_organization_fk.rb` - `20260824120018_add_continuity_import_grants_connection_fk.rb` - `20260824120019_add_continuity_import_grants_actor_fk.rb` - `20260824120020_add_continuity_import_grants_namespace_fk.rb` - `20260824120028_add_session_binding_to_continuity_import_grants.rb` ## Acceptance criteria - `db/structure.sql` after the migrations matches the Table structure section: same columns, nullability, defaults, indexes, foreign keys, and check constraints, under the new names. - Three `import_sync_*` tables and their models are merged to `master`. - A database reviewer has approved the migrations. - All three model specs pass. - A `db/docs/*.yml` entry exists for every table. - Every enum column's check constraint matches the table above. - `import_sync_repositories` has no `test_mode` column and no fixture-account index. - No `import_sync_connections`, `import_sync_webhook_deliveries`, or `import_sync_import_grants` table exists. - No application code beyond the models lands in this MR (no services, workers, controllers). - `Project#import_sync_repository` exists and resolves to the https://gitlab.com/gitlab-org/gitlab/-/work_items/628581 `Import::Sync::Repository` model, ready for later LAND issues to call. `User` has no `installed_import_sync_connections` association; that's gone with the connections table. ## Out of scope - `import_sync_connections`, `import_sync_webhook_deliveries`, and `import_sync_import_grants`. None of the three tables or models is part of this port; they're dropped, not deferred (see the Table structure section above for why there's no connections table, and https://gitlab.com/gitlab-org/gitlab/-/work_items/628586 and https://gitlab.com/gitlab-org/gitlab/-/work_items/628589 for the replacement designs for grants and webhooks). - Any service, worker, or controller (later LAND issues). - Anything under `app/services/continuity/github/test_provider*.rb`, `fixture_repository_resolver.rb`, `set_test_provider_scenario_service.rb`, and `app/services/continuity/projects/test_provider_adapter.rb`. The offline simulator is not ported by any issue. - Callers of the changed `ExternalObject` columns. Only one production file in the PoC reads `local_record_type`/`local_record_id` directly, `app/services/continuity/repositories/work_items/reconcile_object_service.rb`; it is ported and adapted to the new `issue_id`/`merge_request_id`/`note_id` columns in a later issue. Keep the `record!` and `for_local_record` method signatures stable so that file and `lib/gitlab/github_import/importer/events/commented.rb`, which only passes a record into `record!`, need as little change as possible. ## Notes for the reviewer - There is no table-wide unique index on `(provider, provider_installation_id)` any more; that was a `connections`-table index and the table is gone. The partial unique index on `(organization_id, provider_repository_id)` is what the future Cells claim relies on instead: under Cells, `provider_repository_id` is claimed cluster-wide in the Topology Service so the HTTP router can send GitHub webhook deliveries to the owning cell, and a claim needs a single owner per value (see https://gitlab.com/gitlab-org/gitlab/-/work_items/628741). `provider_installation_id` is deliberately not unique: many repositories can share one GitHub App installation, so its index exists only to let the lifecycle handlers and the repair cron look up every repository of one installation, not to enforce one-per-installation. The tables' `gitlab_main_org` classification is still required for the Cells claim to work; do not change it. - The enum table above is the checklist: for each row, confirm the migration's check constraint allows exactly those values and the model's `enum` declaration lists the same integers. - The `external_objects` foreign-key shape is a deliberate departure from the PoC. If you would rather see separate tables per record type, say so on this MR; changing it later is a data migration. --- **OAuth extension tracked separately:** #630400 ("Support GitHub OAuth as a second `provider` on `import_sync_repositories`") proposes extending this table to also support OAuth-connected repositories (a second `provider` value, a nullable `provider_installation_xid`, new OAuth-specific `disconnect_reason` values) once this lands. No change needed to this issue itself.