# 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

```typescript
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

```typescript
// 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

```typescript
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"
};
```

## 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

```typescript
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

```typescript
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

```typescript
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

```http
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

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

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

### Discover Resources

```http
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

```typescript
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](connectors.md)
- [Webhooks](webhooks.md)
- [CI/CD Integration](ci-cd.md)
- [Integration Hub Module](../modules/integration-hub.md)