Integrations Module – Agent Instructions

Module Identity

Module: Integrations
Purpose: Canonical integration catalog for registries, SCM providers, CI systems, repo sources, and runtime hosts.
Deployable: src/Integrations/StellaOps.Integrations.WebService

Directory Layout

src/Integrations/
├── StellaOps.Integrations.WebService/       # ASP.NET Core host
├── __Libraries/
│   ├── StellaOps.Integrations.Core/         # Domain models, enums, events
│   ├── StellaOps.Integrations.Contracts/    # Plugin contracts and DTOs
│   ├── StellaOps.Integrations.Plugins.Abstractions/  # IIntegrationConnectorPlugin
│   ├── StellaOps.Integrations.Persistence/  # PostgreSQL repositories
│   └── StellaOps.Integrations.Testing/      # Shared test fixtures
├── __Plugins/
│   ├── StellaOps.Integrations.Plugin.GitHubApp/
│   ├── StellaOps.Integrations.Plugin.GitLab/
│   ├── StellaOps.Integrations.Plugin.Harbor/
│   ├── StellaOps.Integrations.Plugin.Ecr/
│   ├── StellaOps.Integrations.Plugin.Gcr/
│   ├── StellaOps.Integrations.Plugin.Acr/
│   └── StellaOps.Integrations.Plugin.InMemory/  # Testing / dev
└── __Tests/
    └── StellaOps.Integrations.Tests/

Roles & Responsibilities

Role	Expectations
Backend Engineer	Implement core catalog, plugin loader, API endpoints, event publisher
Plugin Author	Implement `IIntegrationConnectorPlugin` for new providers
QA Engineer	Cover plugin loading, test-connection, health polling, CRUD scenarios
PM/Architect	Keep plugin contracts stable; coordinate cross-module dependencies

Plugin Contract

All connectors implement IIntegrationConnectorPlugin : IAvailabilityPlugin:

public interface IIntegrationConnectorPlugin : IAvailabilityPlugin
{
    IntegrationType Type { get; }
    IntegrationProvider Provider { get; }
    Task<TestConnectionResult> TestConnectionAsync(IntegrationConfig config, CancellationToken ct);
    Task<HealthCheckResult> CheckHealthAsync(IntegrationConfig config, CancellationToken ct);
}

Required Reading

docs/modules/platform/architecture-overview.md
docs/architecture/integrations.md
docs/modules/authority/architecture.md (AuthRef handling)

Constraints

No raw secrets: All credentials use AuthRef URIs resolved at runtime.
Determinism: Stable ordering in listings; UTC timestamps.
Offline-first: All plugin test-connection and health must handle network failure gracefully.
Event emission: Lifecycle events go to Scheduler/Signals via message queue.

Test Coverage

Unit tests in __Tests/StellaOps.Integrations.Tests
Each plugin has its own test class mocking external APIs
Integration tests use StellaOps.Integrations.Plugin.InMemory

2.9 KiB Raw Blame History Unescape Escape