git.stella-ops.org/docs/modules/release-orchestrator/integrations/overview.md

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

Type ID	Description	Discovery Support
docker-registry	Docker Registry v2 API	Yes
docker-hub	Docker Hub	Yes
gcr	Google Container Registry	Yes
ecr	AWS Elastic Container Registry	Yes
acr	Azure Container Registry	Yes
ghcr	GitHub Container Registry	Yes
harbor	Harbor Registry	Yes
jfrog	JFrog Artifactory	Yes
nexus	Sonatype Nexus	Yes
quay	Quay.io	Yes

CI/CD Systems

Type ID	Description	Trigger Support
gitlab-ci	GitLab CI/CD	Yes
github-actions	GitHub Actions	Yes
jenkins	Jenkins	Yes
azure-devops	Azure DevOps Pipelines	Yes
circleci	CircleCI	Yes
teamcity	TeamCity	Yes
drone	Drone CI	Yes

Notification Services

Type ID	Description	Features
slack	Slack	Channels, threads, reactions
teams	Microsoft Teams	Channels, cards
email	Email (SMTP)	Templates, attachments
webhook	Generic Webhook	JSON payloads
pagerduty	PagerDuty	Incidents, alerts
opsgenie	OpsGenie	Alerts, on-call

Secret Stores

Type ID	Description	Features
hashicorp-vault	HashiCorp Vault	KV, Transit, PKI
aws-secrets-manager	AWS Secrets Manager	Rotation, versioning
azure-key-vault	Azure Key Vault	Keys, secrets, certs
gcp-secret-manager	GCP Secret Manager	Versions, labels

Metrics & Monitoring

Type ID	Description	Use Case
prometheus	Prometheus	Canary metrics
datadog	Datadog	APM, logs, metrics
newrelic	New Relic	APM, infra monitoring
dynatrace	Dynatrace	Full-stack 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

Check Type	Description	Frequency
connectivity	TCP/HTTP connectivity	1 min
authentication	Credential validity	5 min
functionality	Full operation test	15 min

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

Error Code	Description	Retry Strategy
INTEGRATION_NOT_FOUND	Integration ID not found	No retry
INTEGRATION_UNHEALTHY	Integration health check failing	Backoff retry
CREDENTIAL_FETCH_FAILED	Cannot fetch credentials	Retry with backoff
CONNECTION_REFUSED	Cannot connect to endpoint	Retry with backoff
AUTHENTICATION_FAILED	Invalid credentials	No retry
RATE_LIMITED	Too many requests	Retry after delay

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