Optional Git account providers

Git integrations use optional packages, owner-scoped credentials and the same TUI/web account catalog. A compatible same-owner shared container does not publish Git credentials to another server user. Provider packages, Git Accounts, server ownership.

Git account integrations are installed packages. The controller remains responsible for encrypted credentials, account history, device polling and cancellation, host authorization, profile revisions and checkout jobs. Provider packages own external HTTP endpoints, identity verification and organization/repository mapping.

Package Account setup Repository browsing
@devctl/provider-github Browser device authorization Accessible organizations and repositories
@devctl/provider-gitlab Access token; GitLab.com or self-hosted HTTPS hostname and optional port Accessible groups, subgroups and projects
@devctl/provider-git-generic HTTPS username and access token Add a repository by URL

Git-provider configuration and workspace Internet policy are separate. In a restricted workspace, a public custom GitLab hostname must also be allowed by the Project's Network settings; the current gateway supports public HTTP/HTTPS on ports 80/443. Controller API authorization for a private GitLab host or a custom HTTPS port does not create a workspace route. Private addresses and other ports remain unavailable through this gateway. Do not disable TLS verification or widen a team's network policy to work around that boundary.

Git launch checks account ownership, repository identity, credential revision and the installed helper configuration. Those checks do not establish network reachability from the workspace. Automatic tenant-scoped private/custom-port Git routes are not implemented; controller catalog access must not be described as proof that workspace Git or glab can reach the same server.

@devctl/git-provider-kit defines the provider-neutral contract. Each integration exports a kind: "git", apiVersion: 1 manifest and createProvider. Manifests describe authentication, default/custom hostnames, username requirements, token help and repository browsing. The TUI/web Git Accounts picker uses these manifests rather than a built-in provider list. Projects → Add project → Browse Git accounts lists accounts with an installed browsing adapter and offers device sign-in only for installed providers that support it.

Install/remove packages using the controller instructions in provider packages. Installed optional dependencies are discovered automatically. DEVCTL_GIT_PROVIDER_PACKAGES overrides discovery with a comma-separated package list; an empty value disables all Git adapters. Restart only the controller consumer to reload its package catalog. Running agent sessions and previously imported credentials are not restarted or revoked.

Removing an adapter preserves stored accounts, encrypted credentials, profile revisions and history. Accounts remain listable and removable. Provider API operations return an explicit 503 when the required package is unavailable; reinstalling it restores those operations. Generic host credential imports remain available for existing accounts and retain their host authorization checks.

The operator API exposes GET /v1/git/providers, account creation/listing under /v1/git/accounts, account owner/repository browsing and provider-neutral device authorization under /v1/git/providers/:provider/device. Historical /v1/github/... URLs and account IDs remain compatible and delegate to the same adapter. They do not contain a second GitHub implementation.

Device codes stay in controller memory and never appear in public responses. Access tokens use the existing encrypted secret store and only cross the authenticated host channel for an explicit import. Packages neither store tokens nor own the controller database. Upstream error bodies and malformed JSON are not returned to the UI. HTTPS requests retain bounded timeouts and reject redirects.

Tests cover device polling/slowdown/cancellation/expiry, scopes, encryption, selected-host imports, pagination, self-hosted repository-origin checks, dynamic picker construction and package removal without losing stored accounts.

Git provider and CLI selection uses the owner-scoped /v1/preferences/git operation and the shared Git Accounts settings. The GitLab manifest declares its native glab sign-in command and supported/unsupported workflow capabilities. Private GitLab API destinations require exact-host administrator approval; tenant provider selection alone cannot permit private network access. See Git Accounts for setup, saved PAT import and OAuth portability.