Integrations Overview

Purpose

The Integration Hub (INTHUB) provides a unified interface for connecting Release Orchestrator to external systems including container registries, CI/CD pipelines, notification services, secret stores, and metrics providers.

Integration Architecture

              INTEGRATION HUB ARCHITECTURE

  ┌─────────────────────────────────────────────────────────────────────────────┐
  │                          INTEGRATION HUB                                     │
  │                                                                             │
  │  ┌─────────────────────────────────────────────────────────────────────┐   │
  │  │                     INTEGRATION MANAGER                              │   │
  │  │                                                                      │   │
  │  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐   │   │
  │  │  │ Type       │  │ Instance   │  │ Health     │  │ Discovery  │   │   │
  │  │  │ Registry   │  │ Manager    │  │ Monitor    │  │ Service    │   │   │
  │  │  └────────────┘  └────────────┘  └────────────┘  └────────────┘   │   │
  │  │                                                                      │   │
  │  └─────────────────────────────────────────────────────────────────────┘   │
  │                                    │                                        │
  │                                    ▼                                        │
  │  ┌─────────────────────────────────────────────────────────────────────┐   │
  │  │                     CONNECTOR RUNTIME                                │   │
  │  │                                                                      │   │
  │  │  ┌──────────────────────────────────────────────────────────────┐   │   │
  │  │  │                  CONNECTOR POOL                               │   │   │
  │  │  │                                                               │   │   │
  │  │  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │   │   │
  │  │  │  │ Docker   │ │ GitLab   │ │ Slack    │ │ Vault    │       │   │   │
  │  │  │  │ Registry │ │ CI       │ │          │ │          │       │   │   │
  │  │  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │   │   │
  │  │  │                                                               │   │   │
  │  │  └──────────────────────────────────────────────────────────────┘   │   │
  │  │                                                                      │   │
  │  └─────────────────────────────────────────────────────────────────────┘   │
  │                                                                             │
  └─────────────────────────────────────────────────────────────────────────────┘
                                       │
       ┌─────────────┬─────────────────┼─────────────────┬─────────────┐
       │             │                 │                 │             │
       ▼             ▼                 ▼                 ▼             ▼
  ┌─────────┐  ┌─────────┐       ┌─────────┐       ┌─────────┐  ┌─────────┐
  │Container│  │ CI/CD   │       │ Notifi- │       │ Secret  │  │ Metrics │
  │Registry │  │ Systems │       │ cations │       │ Stores  │  │ Systems │
  └─────────┘  └─────────┘       └─────────┘       └─────────┘  └─────────┘

Integration Types

Container Registries

CI/CD Systems

Notification Services

Secret Stores

Metrics & Monitoring

Integration Configuration

Integration Entity

interface Integration {
  id: UUID;
  tenantId: UUID;
  typeId: string;           // e.g., "docker-registry"
  name: string;             // Display name
  description?: string;

  // Connection configuration
  config: IntegrationConfig;

  // Credential reference (stored in vault)
  credentialRef: string;

  // Health tracking
  healthStatus: "healthy" | "degraded" | "unhealthy" | "unknown";
  lastHealthCheck?: DateTime;

  // Metadata
  labels: Record<string, string>;
  createdAt: DateTime;
  updatedAt: DateTime;
}

interface IntegrationConfig {
  // Common fields
  url?: string;
  timeout?: number;
  retries?: number;

  // Type-specific fields
  [key: string]: any;
}

Type-Specific Configuration

// Docker Registry
interface DockerRegistryConfig extends IntegrationConfig {
  url: string;                    // https://registry.example.com
  repository?: string;            // Optional default repository
  insecureSkipVerify?: boolean;   // Skip TLS verification
}

// GitLab CI
interface GitLabCIConfig extends IntegrationConfig {
  url: string;                    // https://gitlab.example.com
  projectId: string;              // Project ID or path
  defaultBranch?: string;         // Default ref for triggers
}

// Slack
interface SlackConfig extends IntegrationConfig {
  workspace?: string;             // Workspace identifier
  defaultChannel?: string;        // Default channel for notifications
  iconEmoji?: string;             // Bot icon
}

// HashiCorp Vault
interface VaultConfig extends IntegrationConfig {
  url: string;                    // https://vault.example.com
  namespace?: string;             // Vault namespace
  mountPath: string;              // Secret mount path
  authMethod: "token" | "approle" | "kubernetes";
}

Credential Management

Credentials are never stored in the Release Orchestrator database. Instead, references to external secret stores are used.

Credential Reference Format

vault://vault-integration-id/path/to/secret#key
       └─────────┬────────┘ └─────┬─────┘ └┬┘
              Vault ID       Secret path   Key

Credential Types

type CredentialType =
  | "basic"           // Username/password
  | "token"           // Bearer token
  | "api-key"         // API key
  | "oauth2"          // OAuth2 credentials
  | "service-account" // GCP/K8s service account
  | "certificate";    // Client certificate

interface CredentialReference {
  type: CredentialType;
  ref: string;        // Vault reference
}

// Examples
const dockerCreds: CredentialReference = {
  type: "basic",
  ref: "vault://vault-1/docker/registry.example.com#credentials"
};

const gitlabToken: CredentialReference = {
  type: "token",
  ref: "vault://vault-1/ci/gitlab#access_token"
};

Live Catalog Workflow

The shipped operator workflow is now backed by the Integrations service rather than CLI sample data.

Provider Discovery

• GET /api/v1/integrations/providers returns live provider metadata from the loaded connector plugins.
• Default responses hide test-only providers such as InMemory.
• Each provider entry now advertises:
  • isTestOnly
  • supportsDiscovery
  • supportedResourceTypes

Resource Discovery

• POST /api/v1/integrations/{id}/discover is the supported discovery contract.
• Registry providers discover repositories and tags.
• SCM providers discover projects and repositories.
• CI/CD providers discover jobs and pipelines.
• Object storage providers such as S3Compatible participate in the live catalog and health/test flows, but do not currently advertise discovery.
• Unsupported resource types return 400 with the provider’s supported resource types.

CLI Management Surface

The stella config integrations command group manages the live catalog end-to-end:

stella config integrations providers
stella config integrations list
stella config integrations create --name local-gitlab --type scm --provider gitlabserver --endpoint http://gitlab.stella-ops.local:8929 --authref authref://vault/gitlab#access-token
stella config integrations create --name local-minio --type objectstorage --provider s3compatible --endpoint http://minio.stella-ops.local:9000
stella config integrations test <integration-id>
stella config integrations discover <integration-id> --resource-type projects

Deprecated stella integrations * routes are preserved as aliases and forward to stella config integrations *.

Health Monitoring

Health Check Types

Health Check Flow

interface HealthCheckResult {
  integrationId: UUID;
  checkType: string;
  status: "healthy" | "degraded" | "unhealthy";
  latencyMs: number;
  message?: string;
  checkedAt: DateTime;
}

class IntegrationHealthMonitor {
  async checkHealth(integration: Integration): Promise<HealthCheckResult> {
    const connector = this.connectorPool.get(integration.typeId);
    const startTime = Date.now();

    try {
      // Connectivity check
      await connector.ping(integration.config);

      // Authentication check
      const creds = await this.fetchCredentials(integration.credentialRef);
      await connector.authenticate(integration.config, creds);

      return {
        integrationId: integration.id,
        checkType: "full",
        status: "healthy",
        latencyMs: Date.now() - startTime,
        checkedAt: new Date()
      };
    } catch (error) {
      return {
        integrationId: integration.id,
        checkType: "full",
        status: this.classifyError(error),
        latencyMs: Date.now() - startTime,
        message: error.message,
        checkedAt: new Date()
      };
    }
  }
}

Discovery Service

Integrations can discover resources from connected systems.

Discovery Operations

interface DiscoveryService {
  // Discover available repositories
  discoverRepositories(integrationId: UUID): Promise<Repository[]>;

  // Discover tags/versions
  discoverTags(integrationId: UUID, repository: string): Promise<Tag[]>;

  // Discover pipelines
  discoverPipelines(integrationId: UUID): Promise<Pipeline[]>;

  // Discover notification channels
  discoverChannels(integrationId: UUID): Promise<Channel[]>;
}

// Example: Discover Docker repositories
const repos = await discoveryService.discoverRepositories(dockerIntegrationId);
// Returns: [{ name: "myapp", tags: ["latest", "v1.0.0", ...] }, ...]

Discovery Caching

interface DiscoveryCache {
  key: string;              // integration_id:resource_type
  data: any;
  discoveredAt: DateTime;
  ttlSeconds: number;
}

// Cache TTLs by resource type
const cacheTTLs = {
  repositories: 3600,     // 1 hour
  tags: 300,              // 5 minutes
  pipelines: 3600,        // 1 hour
  channels: 86400         // 24 hours
};

API Reference

Create Integration

POST /api/v1/integrations
Content-Type: application/json

{
  "typeId": "docker-registry",
  "name": "Production Registry",
  "config": {
    "url": "https://registry.example.com",
    "repository": "myorg"
  },
  "credentialRef": "vault://vault-1/docker/prod-registry#credentials",
  "labels": {
    "environment": "production"
  }
}

Test Integration

POST /api/v1/integrations/{id}/test

Response:

{
  "success": true,
  "data": {
    "connectivityTest": { "status": "passed", "latencyMs": 45 },
    "authenticationTest": { "status": "passed", "latencyMs": 120 },
    "functionalityTest": { "status": "passed", "latencyMs": 230 }
  }
}

Discover Resources

POST /api/v1/integrations/{id}/discover
Content-Type: application/json

{
  "resourceType": "repositories",
  "filter": {
    "namePattern": "myapp-*"
  }
}

Error Handling

Integration Errors

Circuit Breaker

interface CircuitBreakerConfig {
  failureThreshold: number;     // Failures before opening
  successThreshold: number;     // Successes to close
  timeout: number;              // Time in open state (ms)
}

// Default configuration
const defaultCircuitBreaker: CircuitBreakerConfig = {
  failureThreshold: 5,
  successThreshold: 3,
  timeout: 60000
};

References

• Connectors
• Webhooks
• CI/CD Integration
• Integration Hub Module