Docs · Hangar

Any forge, any registry

Status: proposal, for decision (2026-10-15). Nothing here is built.

A plan to run Hangar on GitLab and Bitbucket as well as GitHub, and to publish images to any OCI registry as well as GHCR, without changing what Hangar is. The illustrated version, with the same content, is in the Library; the six one-page diagrams are in diagrams/ and in the diagram gallery.

Verdict

Feasible, in six phases, about 24 weeks for one person. Tekton, Pipelines as Code, Argo CD, External Secrets, Crossplane and cosign already work with GitLab and Bitbucket. GitHub is wired in at about a hundred small places (a literal owner, a curl to api.github.com, a hardcoded link) and at three load-bearing ones:

1. The control plane writes to repositories through provider-upjet-github: 81 templates in 9 compositions, 88 live resources on the dev cluster (24 Repository, 64 RepositoryFile). provider-gitlab has no file resource, there is no maintained Bitbucket Cloud provider, and this provider caused the September data loss and rate-limit storms.
2. CI tokens are GitHub App installation tokens. The never-persisted credential model is built on a GitHub feature GitLab and Bitbucket do not have in the same form.
3. An app is identified by github.com/project-slug. Tower authorization (ACC-05), release approvers and the catalog app list key on it, and its split('/') assumes a one-segment owner that GitLab subgroups break.

Recommendation: two Hangar-owned contracts, SCM and registry, with each vendor as a driver. Move the GitHub path onto them first with no visible change (phases 0 to 2, which also removes the RepositoryFile bug class), then GitLab as the proof (phase 3), then Bitbucket (phase 4). The forge and the registry become separate choices: Bitbucket has no registry of its own.

What is coupled today

Already neutral: Tekton and Pipelines as Code (GitLab, Bitbucket Cloud and Data Center are supported providers), Argo CD, the registry-credentials ClusterExternalSecret, cosign and Rekor, Apron’s scm.host/scm.owner, and the terasky ingestor’s publish step (gitlab, bitbucket, bitbucketcloud targets, checked in the installed source).

Principles

• Separate the forge from the registry. The image path comes from registry config, never from the forge owner.
• Hangar names things. scm.hangar.io resources, hangar.io/app identity, an scm CLI. Vendors are drivers.
• GitHub moves first. Nothing reaches GitLab until GitHub runs on the contracts with no visible change.
• Capabilities, not the lowest common denominator. A driver declares what it can enforce; Tower shows the real level.
• Write the credential delta down. Weaker is allowed; silent is not.
• Adopt, never recreate. Every migration step observes existing repos by name and may neither commit nor delete.

Target architecture

SCM contract, one Go library with three faces:

• Declarative: provider-hangar-scm, a native Crossplane provider serving scm.hangar.io/v1alpha1 Repository, RepositoryFile, Webhook and MergeGate. A ProviderConfig per forge picks the driver, so compositions keep one shape. RepositoryFile.spec.mode is seed (create once if absent, never update or delete) or managed (the tenants-repo identity files).
• Imperative: an scm CLI in the Glidepath toolbox image (scm pr open|find|comment, scm status, scm contents get, scm compare, scm pr-for-commit, scm gate apply) replacing the inline curl, and a broker endpoint /scm-token beside /github-installation-token.
• Tower: a TypeScript ScmClient and RegistryClient in the Backstage backend, drivers on @backstage/integration (which already handles GitLab, Bitbucket Cloud and Bitbucket Server credentials), run against the same recorded conformance fixtures.

Registry contract: plain OCI for push, pull, digest, tags, referrers and cosign, with the standard bearer challenge instead of ghcr.ts’s GHCR token exchange. Drivers only for listing with dates and deleting. Config: registry.host, registry.namespace; image path <host>/<namespace>/<app>, previews -pr.

Identity: hangar.io/app, hangar.io/forge, hangar.io/source-location. Tower authorization reads hangar.io/app. Namespaces may have several segments (GitLab subgroups, Bitbucket workspace and project).

Sign-in: OIDC through Dex (already in the cluster; GitHub, GitLab and Bitbucket Cloud connectors), users still matched to catalog Users.

Decision: how the control plane writes to a forge

The SCM contract, operation by operation

Check each endpoint against the vendor reference when its driver is written; the Data Center column is unverified.

The registry contract

A Bitbucket fleet must pick a registry. Harbor is the recommended neutral default.

Credentials, forge by forge

Bitbucket Cloud removed app passwords on 2026-07-28. Plan tiers change what can be enforced; check vendor pricing before choosing a lab plan.

The proof: one release on GitLab

What changes, product by product

• Airframe: scm.hangar.io replaces repo.github.m.upbound.io (the _shared partials keep the diff small); owner, host and registry from the cluster registry entry; optional spec.source on app XRDs; a Webhook per repo off GitHub; the Go module path follows the source host.
• Glidepath: the scm CLI replaces curl, one Task per PR (ADR-0026, the SCM contract); platformIdentity.githubOwner becomes platformIdentity.source; image-repo from registry config; /scm-token and the PaC secret rotator; github-ruleset.md becomes merge-gate.md, rendered by scm gate apply.
• Tower and Backstage: ScmClient and RegistryClient, with today’s GitHub code as the first driver; authorization and approvers read hangar.io/app; integrations, scaffolder publish and ingestor target per forge; sign-in through Dex; each app shows its forge and merge-gate level.
• Apron, Autopilot, Hangar: cluster.yaml gains scm.forge, scm.namespace, registry.*; provider-github removed after phase 2; agent images from registry config; business rules PPL-01, PPL-02, ACC-05, GATE-03 and GATE-06 reworded per forge as each lands (business rules).

Moving the GitHub fleet first

Roadmap

Decisions needed

Risks

• Rate limits: Bitbucket Cloud’s hourly budget is far smaller than GitHub’s. Seed files are never re-read after the scaffold ledger marks them done; conditional reads where supported; a per-forge budget metric trips a breaker.
• Nested namespaces break every owner/repo parse (Tower, the broker’s verifyAppOwnsRepo, Glidepath’s git-url). Fixed on GitHub in P0.
• Webhooks per repo: more objects and secrets, each a Webhook with its own rotated secret.
• Test matrix: recorded conformance fixtures on every PR, one live lane per forge nightly.
• Plan tiers: Tower reports the level the driver measured, never an assumed one.
• Owning a provider is code to maintain, set against retiring one that needed a fleet-wide pause.

What was checked

origin/main of airframe, glidepath, tower, backstage, apron and hangar, and autopilot main (counts from git grep over deployable files); the live dev cluster, read only (24 Repository and 64 RepositoryFile resources, none paused; none on the prod cluster); the installed terasky ingestor source; vendor sources for Pipelines as Code providers, the PaC GitLab token Secret, provider-gitlab’s resources and Bitbucket’s app password removal. Not verified: plan-tier features, Bitbucket rate limits and Data Center endpoints, GitLab conditional-read coverage.