DocsOperationsLifecycle architecture

Lifecycle architecture

Understand how requests become Lifecycle Environments and plan dependencies, security controls, availability, and recovery.

Lifecycle receives requests, builds applications, and deploys Environments to Kubernetes. The following flow shows the components and dependencies that operators must configure.

Request-to-Environment flow

  1. GitHub delivers a repository event, or an authenticated user calls the UI, CLI, or v2 API.
  2. Lifecycle authenticates the request and checks the applicable policy.
  3. Lifecycle uses Postgres for Lifecycle data and Redis for queued work.
  4. Lifecycle reads lifecycle.yaml and selects the applicable Services.
  5. Lifecycle builds images or invokes external pipelines and applies workloads to Kubernetes.
  6. When enabled, object storage keeps archived logs and Site content.
  7. The UI, CLI, API, GitHub comments, and MCP surfaces show the resulting status and logs.
  8. When one of these events occurs, Lifecycle removes the Environment:
    • A pull request closes.
    • A user requests removal.
    • The Environment TTL expires.
    • The API lease expires.

Components

ComponentResponsibility
WebReceives UI, API, and GitHub requests and applies authentication
WorkerRuns build, deploy, Agent, Site, and cleanup work
GatewayServes Site content when the Sites feature is enabled
Lifecycle UIProvides Environments, Sites, Agents, and Settings
KeycloakProvides identity services for the chart authentication configuration
PostgresStores Lifecycle data, including Environments and configuration
RedisCoordinates queued work for web and worker components
BuildKit / registryBuilds and distributes images when the native build configuration is used
KubernetesRuns Environment workloads, jobs, Services, ingress, and Secrets
Object storageStores archived build and deploy logs and Site content when configured

Availability and recovery boundaries

The default values use one web replica, one worker replica, and standalone Redis. This configuration is not a high-availability profile.

  • Monitor Postgres and Redis as separate dependencies. /api/health returns Unhealthy when either dependency is unavailable. It does not check object storage.
  • Back up Postgres, configuration Secrets, and the ENCRYPTION_KEY Secret as one recovery set. Test the matched restore in an isolated deployment.
  • Decide whether Redis queued-work state must survive a recovery. After an outage or data loss, examine affected Environments before a retry.
  • When archived logs or Sites must survive a failure, back up object storage and its credential Secret. Test the object storage restore with the related Lifecycle data.

Trust boundaries

  • The default ClusterRole has wildcard Kubernetes permissions. Limit cluster and network access before you expose Lifecycle.
  • Use ENABLE_AUTH=false only in an isolated local evaluation. Requests get administrator permissions in this mode.
  • GitHub App installation, Lifecycle repository onboarding, and a user’s linked GitHub identity are separate authorization relationships.
  • Restrict access to the ENCRYPTION_KEY. If you lose this key, Lifecycle cannot decrypt protected configuration.
  • Review the permissions, approvals, credentials, and network access for each Agent tool and external MCP connection.

Continue with Security boundaries, configuration surfaces, and day-two operations.

Optional configurationRuntime configuration surfaces