ADR-0017: GitLab sources and provider seams
- Status: Accepted
- Date: 2026-09-16
Context
ADR-0016 gave a Project several integration sources, but GitHub was still the
only kind: SourceType had one value, and GitHubApiClient and
GitHubRepositoryAccess were wired straight into the source setup, the change
worker, and the history import. GitLab is the next source, and unlike GitHub it
is not one address: an Organization may run its own instance. It also proves its
deliveries in two different ways, depending on how the webhook was set up.
Decision
- Two provider seams, no more. The
changecapability owns two small ports,ChangedFileCollectorandSourceHistoryReader, each with one implementation per source type and a registry that fails at startup if a type has none. The workers keep every decision they already made — retries, the item limit, thepage:offsetcursor, stale recovery — and only the provider call, the "an older item ends the scan" rule, and the error code vary. - A
sourcepackage for the shared vocabulary.SourceType,ChangedFile(Kind),ChangedFiles,ProviderListing,ProviderAccess,WebhookAuthMode, andSourceCredentialsmoved out ofgithub, sogithubandgitlabare adapters that depend on the vocabulary rather than on each other. The stored failure codes did not change. - A GitLab project is named only by its path.
external_project_keyholdsgroup/project, with any number of subgroups;repository_ownerandrepository_namebecame nullable and are GitHub's alone. A key is unique per Organization and source type, so the same name on both providers is two sources. - The instance is allowlisted, not free. A GitLab source carries an
api_base_url, the only provider address a request may choose.GitLabBaseUrlaccepts it only if it is a plain HTTP or HTTPS address — no credentials, query, or fragment — whose origin is inreleaseflow.gitlab.allowed-hosts(gitlab.comby default). An entry ishostorhost:port, meaning HTTPS, or a full origin such ashttp://gitlab.internal:8080; writing the scheme is the only way a deployment accepts an instance reached without TLS. The allowlist is checked again before every call, and redirects are never followed, so a redirect cannot move a call to another host. - One secret, two ways to prove a delivery. ReleaseFlow generates the secret
and reveals it once, exactly as for GitHub, and the administrator pastes it
into GitLab.
webhook_auth_moderecords which check applies:GITLAB_SIGNING_TOKENverifies the Standard Webhooks headers —webhook-id,webhook-timestamp, and awebhook-signatureofid.timestamp.body, any one of several space-separated candidates, within five minutes of the clock — andGITLAB_SECRET_TOKENcomparesX-Gitlab-Tokenwith the secret in constant time. Every failure answers401 webhook_signature_invalid. - A GitLab change may have no delivery ID. GitLab identifies a delivery only
in its signing mode, and not always with a GUID, so a change records
X-Gitlab-Event-UUIDwhen it is one and nothing otherwise. The database now only requires that an imported change has no delivery ID. - A withheld diff is unavailable, never empty. The changed files come from
the merge request's diffs, at most ten pages of a hundred. A diff GitLab marks
collapsed,too_large, ortruncatedmakes the whole list unavailable, so a file that was never seen is never declared safe. - GitLab is read in the other direction. The import asks for the merge requests updated after the window's start, least recently updated first, so the list only grows at its end and a resumed import reads the same page again.
Consequences
- One Project can gather GitHub repositories and GitLab projects, and both reach the same intake, classification, AI, review, and release notes.
- A deployment decides which GitLab instances exist. A self-managed instance
needs an entry in
RELEASEFLOW_GITLAB_ALLOWED_HOSTS, and removing one stops its sources from being called at all. - A squashed or fast-forwarded merge request has no merge commit, so the commit a change records falls back to the squash commit and then to the head commit. A webhook delivery carries no merge time, so the last update stands in for it.
- Linear and Jira will add their own
SourceType, their own implementation of each port, and their own columns; neither worker should need to change again. - Commit messages, which the old project read to find Jira keys, are not collected yet. They arrive with Jira enrichment, for both providers at once.