Integrations

Verified against commit 942a18727c on 2026-09-26 (UTC) for Status, Deployables, API Surface, Background services, Doctor checks and Configuration. Re-verify: grep -n "AddHostedService\|AddServiceDoctorChecks\|serviceName:" src/Integrations/StellaOps.Integrations.WebService/Program.cs and grep -n "^ integrations-web:" devops/release/bundle/docker-compose.yml.

Service rows (host project, image, database and role, compose file, bundle presence, Doctor registration) are generated in docs/architecture/service-inventory.md; where this page and the inventory differ, the inventory is authoritative.

The Integrations module is the central catalog and connector hub for managing external-tool integrations across the Stella Ops platform. It is the reference for operators registering connectors and for engineers consuming the integration catalog from other modules.

Purpose

Integrations provides a unified API for registering, configuring, and health-checking third-party service connectors such as GitHub, GitLab, and Harbor. It is the single source of truth for all external-tool configurations, letting other modules discover and consume integration details without embedding provider-specific logic.

Quick Links

• Architecture - Technical design and implementation details
• API Reference - Endpoint and DTO reference

Status

The child runner for process-isolated connectors (src/Integrations/StellaOps.Integrations.PluginHost.ProcessRunner/) ships inside the integrations-web image. The auto-sbom-readiness-e2e CI lane provisions this service’s own database and checks it directly (SPRINT_20260916_005 FAN-6, green on main 2026-09-26).

Quarantined surfaces (not shippable in this release)

Two SCM-feedback surfaces are built but quarantined per PLAN_20260704 findings A4/A5 and decision D3 (quarantine, not delete) — they are preserved for a future SCM-feedback initiative but are not wired and must not be presented as available:

• Commit-/PR-time webhook scanning (StellaOps.Scanner.Sources triggers). The scanner webhook endpoints return a deterministic 501 source_scan_not_available because the dispatcher’s IScanJobQueue has no production registration.
• Outbound SCM annotations / SARIF push — GitHubAppAnnotationClient / GitLabAnnotationClient (marked internal) and the stella github CLI verbs, which exit with a clean not available in this release error (no IGitHubCodeScanningClient is DI-registered).

The sanctioned scan ingress and feedback path is CLI-in-CI: emit SBOM/SARIF with the scanner (stella sbom generate / stella sbom attach, stella registry scan --wait --json then stella scan sarif --scan-id) in your pipeline and upload with the platform’s own action (e.g. github/codeql-action/upload-sarif).

Key Features

• Plugin-based connector architecture: Extensible provider system whose host-compiled connector set is now limited to host-local S3-compatible object storage and feed mirrors. GitHub App, GitLab, Gitea, Harbor, Docker Registry / GitLab Container Registry, Jenkins, Nexus, Vault, Consul, and the eBPF Agent are no longer compiled into StellaOps.Integrations.WebService; they require signed/profile-mounted connector bundles before they appear in provider discovery. The IntegrationProvider enum additionally declares providers without bespoke plugins yet (ECR, GCR, ACR, Docker Hub, Quay, Artifactory, Bitbucket, Azure DevOps, CI/CD systems, package-repo sources, symbol/feed mirrors, and a generic Custom provider). The in-memory double (InMemory provider) stays in explicit test harnesses.
• Fail-closed external plugin admission: Directory-loaded connector DLLs are disabled by default and must pass configured signature verification before they are considered. Production also requires a healthy stellaops.pluginhost.process.v1 runner handshake plus fail-closed operation IPC. Signed process-backed connectors can execute allowlisted integration:test-connection, integration:health-check, and integration:discovery operations in a child runner; authref-backed operations use a one-use named-pipe secret broker so the generic IPC carries only opaque handles. Dead runner paths return deterministic lifecycle evidence, and broader execution still waits on long-lived supervision, platform hard resource controls, process-tree accounting, and broker channel peer-identity hardening.
• Signed connector bundle manifests: Optional connector payloads can be mounted as directory bundles containing stellaops.integration-plugin.json. The manifest declares id, version, relative assembly, provider/type aliases, capability ids (integration:test-connection, integration:health-check, integration:discovery, and integration:credential-materialization when brokered authref materialization is needed), detached signature metadata, trust-root labels, and profile membership.
• Cloud registry token exchange (in-connector, offline-first): The Docker Registry connector bundle performs the provider-native credential exchange for the AWS ECR, Google Artifact Registry / GCR, and Azure Container Registry descriptors before authenticating against the OCI /v2/ surface. ECR SigV4-signs a GetAuthorizationToken request from a raw IAM key pair; GCR mints an RS256 service-account JWT bearer grant; ACR runs an AAD client-credentials + /oauth2/exchange round-trip. All signing is BCL-only (System.Security.Cryptography — no AWS/Google/Azure SDK is referenced, preserving the air-gap and supply-chain posture). Every exchange endpoint is overridable through the integration’s ExtendedConfig (ecrTokenEndpoint/awsRegion, gcpTokenEndpoint, aadAuthority/azureTenantId/azureScope) so the exchange works air-gapped and can be pointed at a private STS/token mirror; pre-exchanged credentials (AWS:<pwd>, oauth2accesstoken:<token>, 00000000-…:<rt>) and non-cloud descriptors pass through unchanged. A failed exchange surfaces as a failed test/health/discover — never a silent anonymous fall-through. The forwardable (non-secret) ExtendedConfig endpoint keys are propagated to the process-isolated runner so overrides apply under process isolation. Implementation: StellaOps.Integrations.Plugin.DockerRegistry.CloudRegistryTokenExchange.
• Health checks: Per-integration health probing with durable latest-status tracking
• Explicit credential backends: Every integration declares its credential backend explicitly — inline (Stella-managed AEAD-sealed ciphertext), authref (URI reference to an external vault), or none (anonymous integration). The legacy none + non-null auth_ref_uri back-compat shape was dropped in Sprint 032; registration rejects it with HTTP 400 and the DB enforces the canonical shape via a CHECK constraint. See architecture.md for the resolution model and the canonical operator workflow (devops/agents-targets/scripts/customer-onboarding/01b-register-inline-integrations.sh).
• Tenant isolation: All integrations are scoped to a tenant; cross-tenant access is prohibited
• AiCodeGuard pipeline support: Integrations participate in AI-assisted code review pipelines
• Plugin discovery: Automatic detection and registration of available connector plugins

API Surface

All catalog endpoints are mounted under /api/v1/integrations, require a valid tenant (RequireTenant()), and are authorized by the integration scopes below. (Grounded in IntegrationEndpoints.MapIntegrationEndpoints.)

Every route under /api/v1/integrations and /api/v1/secret-authority is also mapped under the consolidated root /api/integrations/v1 (Endpoints/IntegrationsConsolidatedRouteAliases.cs).

Adjacent route groups:

• Secret Authority (/api/v1/secret-authority) — GET /targets (integration:read) lists secrets-manager integrations that can stage authref bundles; PUT /bundles/{bundleId} (integration:write) writes a credential bundle and returns authref bindings.
• Internal crypto re-seal (/internal/crypto/...) — installation-wide KEK rotation endpoints fanned out by Platform. Population/progress reads require an authenticated principal with crypto:kek:read, crypto:kek:rotate, or ops.admin; start/abort require an authenticated principal with crypto:kek:rotate or ops.admin. Platform forwards a validated operator Bearer token or relays the gateway-signed identity envelope after local verification, and Integrations verifies/re-authorizes it. Network bypass alone cannot satisfy these policies. The default internal HTTP transport is not mTLS; certificate-bound transport remains pending and must not be inferred from the /internal path.
• Health probes — GET /health, /health/liveness, /health/readiness (anonymous, for the Router gateway and orchestrator).

Background services

Hosted services registered in Program.cs: SecretProviderBootProbe, RegistryWriteDriftMonitor, IntegrationHealthMonitor (periodic provider health sweep, Integrations:HealthMonitor:*), RegistryAutoScanSweepService, and ScannerProjectionService when ScannerProjection:Enabled is true.

Doctor checks

AddServiceDoctorChecks("integrations") and five module checks in StellaOps.Integrations.WebService/Doctor/IntegrationsDoctorChecks.cs (credential-custody KEK, own-database cutover, Policy decisions owner API, registry credential readiness, local Scanner projection).

Dependencies

Upstream (this module depends on)

• Authority - Authentication and authorization for API access
• Plugin Framework - Plugin lifecycle and discovery infrastructure

Downstream (modules that depend on this)

Cross-module consumers do not read the Integrations database directly. They depend only on StellaOps.Integrations.Contracts and resolve entries through the read-only IIntegrationCatalog seam, whose HTTP implementation calls GET /api/v1/integrations/{id} with the caller’s bearer (tenant resolved from the stellaops:tenant claim, integration:read enforced). When no base address is configured, each consumer falls back to a fail-closed NullIntegrationCatalog.

• Scanner - SCM bulk import resolves SCM integrations via HttpIntegrationCatalog (registered when Scanner:Integrations:BaseAddress is set).
• Release Orchestrator - Registry version sync and deployment-bundle registry credentials resolve registry integrations via HttpIntegrationCatalog (registered when ReleaseOrchestrator:Integrations:BaseAddress is set).

Note: as of the source reviewed, Signals (SCM webhooks) and the Job Engine / Orchestrator do not consume the Integrations catalog seam. Earlier drafts listing them as downstream consumers were inaccurate.

Configuration

Key settings (grounded in Program.cs):

• PostgreSQL connection: STELLAOPS_POSTGRES_INTEGRATIONS_CONNECTION, with Postgres:Integrations:ConnectionString as the exact host/test override. The service fails closed without its own stellaops_integrations DSN; no generic ConnectionStrings:Default fallback exists. Schema integrations converges from the canonical embedded SQL baseline on every startup (EF Core remains the query/materialization layer, not the DDL authority).
• Authority resource-server authentication (AddStellaOpsResourceServerAuthentication).
• Plugin discovery directory: Integrations:PluginsDirectory (defaults to <baseDir>/plugins); external directory plugins are gated by the Integrations:PluginAdmission options (IntegrationPluginAdmissionOptions).
• Profile-mounted connector bundle roots: Integrations:PluginProfileRoots is an ordered set of optional directories. Each existing root is loaded in deterministic path order; the root directory name must appear in each bundle manifest’s profiles[] membership.
• Inline credential master KEK: Integrations:SecretProtectionKey → Platform:Setup:SecretProtectionKey → STELLAOPS_SECRETS_ENCRYPTION_KEY → STELLAOPS_BOOTSTRAP_KEY (AEAD aadPrefix integration-cred, kdfLabel stellaops-integration-credentials-v1).
• Vault AuthRef resolver address: VAULT_ADDR (defaults to http://vault.stella-ops.local:8200).
• External connector pagination / API-version options are owned by their signed bundles and mounted profile configuration under devops/etc/plugins/integrations/. The WebService still owns the shared resilient-HTTP pipeline (retry-with-jitter + circuit breaker + timeout) and host-local connector defaults.

Current packaged connector profiles:

• recommended: Vault, Harbor, GitHubApp, DockerRegistry / GitLab Container Registry.
• harness: InMemory test connector only.
• integrations-scm-ci: Gitea, Jenkins, Nexus, and GitLab Server / GitLab CI.
• secrets-optional: Consul.
• runtime-host: eBPF Agent.

The recommended overlay intentionally leaves Integrations:PluginsDirectory empty and uses Integrations:PluginProfileRoots for the recommended root; base mirror/storage connectors remain host-owned in this migration slice.

Scopes (Authority)

The service registers exactly three integration scopes (StellaOpsScopes):

• integration:read — list/get/health/impact/providers, and the Secret Authority read surface.
• integration:write — create/update/delete, and Secret Authority bundle staging.
• integration:operate — test-connection, resolve-credentials, discovery, and AI Code Guard runs.

IDE Extensions (VS Code, JetBrains)

As of Sprint 214, the IDE extension plugins (previously src/Extensions/) are housed under src/Integrations/__Extensions/. These are non-.NET projects (TypeScript for VS Code, Kotlin for JetBrains) that act as thin API clients for the Orchestrator and Authority services. See the Architecture doc for details.

Subordinate documents

Related Documentation

• Plugin Framework - Underlying plugin infrastructure
• Scanner - SCM bulk-import consumer of the integration catalog
• Release Orchestrator - Registry version-sync and deployment-bundle credential consumer of the integration catalog