0030 - Use GitLab registry and Terraform state for ECS services

Date

2026-04-29

Status

Accepted

Context

BetterFleet service repositories deploy ECS-backed applications through GitLab CI. Existing services such as bf-telematics, bf-manage-core, bf-manage-connect, bf-manage-sitepwrmon, and bf-schedule-creator build Docker images in CI, push them to the GitLab Container Registry, and deploy Terraform using GitLab-managed HTTP state through the current project.

Consistent CI and deployment wiring reduces setup work, makes service pipelines easier to compare, and keeps platform assumptions visible in one place.

Decision

We will use the GitLab Container Registry as the default Docker image registry for BetterFleet ECS service deployments.

We will use GitLab-managed Terraform HTTP state in the current GitLab project by default, addressed through GitLab CI variables such as CI_API_V4_URL, CI_PROJECT_ID, and a service-specific state name.

ECS service Terraform should receive the image repository and version through TF_VAR_task_container_registry and TF_VAR_task_container_version, matching the existing service repository pattern.

Use a different registry or a different Terraform state project only when there is a documented reason, such as a platform ownership boundary, external deployment target, retention requirement, or security constraint. That exception should be recorded in the repo that owns the deployment, and should be promoted to a new or updated ADR if it becomes a repeated pattern.

Consequences

• New ECS service deployments need fewer bespoke CI variables.
• Service pipelines can share the same mental model for Docker image publishing and Terraform state.
• GitLab project access controls become part of the deployment boundary for service images and service-owned Terraform state.
• AWS ECR remains available for workloads that need it, but it is an exception to document rather than the default.
• Existing services that already follow the GitLab registry and state pattern remain aligned.
• Existing services that use a different pattern should keep working, but future changes should either align them or document the reason for the exception.