SCM Integrations Architecture

Cloud Agents may only operate on repositories authorized through application connections. Users never paste personal access tokens or SSH private keys for Cloud Agent clone/push.

Everything lives in this monorepo:

Gateway APIs + store: packages/cfactory-gateway-server (integrations.ts, cp_scm_* tables, clone credential mint)
Admin UI: packages/cfactory-admin → Integrations
Shared types + CLI client: @cfactory/cfactory-gateway (src/scm/)

There is no separate CFactory-Org/cloud repository for this surface.

Providers

Provider	Application model	Cloud Agent eligible
GitHub	CFactoryConnect GitHub App → installation access tokens	Yes
GitLab	CFactory OAuth Application (refresh tokens). PAT connections are not eligible for new Cloud Agent sessions	OAuth only
Azure DevOps	Multi-tenant Entra ID app → service principal added to the ADO org with repository ACLs → short-lived Entra tokens for git	Entra-backed orgs only

Adapter contract

cfactory-gateway-server implements the HTTP surface behind ScmProviderAdapter:

connect / listInstallations / listRepos
mintCloneCredentials(repoId) → short-lived HTTPS username/password (never user PAT/SSH)
Session create: POST /api/cloud-agents/sessions with { provider, repoId } — server binds cloneUrl from the authorized repo record

Error codes: integration_required, repo_not_authorized, provider_unsupported, pat_not_allowed, entra_org_required.

Cloud Agent session gate

UI / CLI lists only Integration-authorized repos.
POST /api/cloud-agents/sessions refuses free-text paths / arbitrary clone URLs.
LLM defense: when X-CFACTORY-FEATURE: cloud-agent, require a verified org project with non-empty repos[] (and optional remote allowlist match). Basename auto-create is disabled for this feature.

Azure DevOps app → repositories

Azure DevOps has no GitHub-App marketplace install. The supported app path is:

Customer consents the CFactory Entra application.
An ADO admin adds the resulting service principal to the Azure DevOps organization and grants repository permissions.
The gateway mints Entra access tokens (Azure DevOps resource) for HTTPS git.

CLI

cfactory scm connect github
cfactory scm connect gitlab
cfactory scm connect azure_devops
cfactory scm list

Set CFACTORY_API_URL (or CFACTORY_API_BASE) to your gateway public URL when not using the default API host.

Local testing

Step-by-step stack, smoke script, and CLI stand-in: Testing Cloud Agents Locally.

Provider modules (gateway-server)

Application auth is implemented as provider adapters under packages/cfactory-gateway-server/src/scm/providers/:

Module	Responsibility
`providers/github.ts`	GitHub App JWT, installation tokens, repo list
`providers/gitlab.ts`	OAuth code/refresh, project list
`providers/azure-devops.ts`	Entra code/refresh, repo list
`service.ts`	Mint + sync orchestration
`routes.ts`	Thin HTTP (`/start`, `/callback`, CRUD, sessions)

Happy path: POST /api/integrations/:provider/start → provider consent → /callback → sealed credentials + synced repos. Manual Admin CRUD remains a dev fallback only.