Operational Guides

Setup ECR Access

How to configure your project to push and pull Docker images using the central OIDC roles.

New

Overview

The central infra provides OIDC roles for ECR access. Your project needs to:

Create its own ECR repository (in your project's .infra/)
Use the central OIDC roles in GitHub Actions workflows

See ADR-001 for why this hybrid model exists.

Step 1: Create Your ECR Repository

In your project's Terraform (.infra/ecr.tf):

resource "aws_ecr_repository" "my_service" {
  name                 = "myproject/my-service"
  image_tag_mutability = "IMMUTABLE"

  image_scanning_configuration {
    scan_on_push = true
  }

  tags = {
    Project   = "myproject"
    ManagedBy = "terraform"
  }
}

resource "aws_ecr_lifecycle_policy" "my_service" {
  repository = aws_ecr_repository.my_service.name

  policy = jsonencode({
    rules = [
      {
        rulePriority = 1
        description  = "Keep last 10 tagged images"
        selection = {
          tagStatus     = "tagged"
          tagPrefixList = ["v"]
          countType     = "imageCountMoreThan"
          countNumber   = 10
        }
        action = { type = "expire" }
      },
      {
        rulePriority = 2
        description  = "Remove untagged images after 7 days"
        selection = {
          tagStatus   = "untagged"
          countType   = "sinceImagePushed"
          countUnit   = "days"
          countNumber = 7
        }
        action = { type = "expire" }
      }
    ]
  })
}

Naming convention: {project}/{image} (e.g., maxcolchon/agent-support).

Step 2: Add GitHub Repository Secret

Add the AWS account ID as a repository secret:

Repository Settings → Secrets and variables → Actions
Add secret: AWS_ACCOUNT_ID = {ACCOUNT_ID}

This is the only secret needed — no AWS access keys required.

Step 3: Use OIDC Roles in Workflows

Pull access (CI):

permissions:
  id-token: write
  contents: read

steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::${{ secrets.AWS_ACCOUNT_ID }}:role/GitHubActions-ECR-PullRole
      aws-region: eu-central-1

  - uses: aws-actions/amazon-ecr-login@v2

Push access (releases):

permissions:
  id-token: write
  contents: read

steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::${{ secrets.AWS_ACCOUNT_ID }}:role/GitHubActions-ECR-PushRole
      aws-region: eu-central-1

  - uses: aws-actions/amazon-ecr-login@v2

Registry URL: {ACCOUNT_ID}.dkr.ecr.eu-central-1.amazonaws.com

Recommended Settings

Setting	Value	Rationale
`image_tag_mutability`	`IMMUTABLE`	Prevents overwriting released versions
`scan_on_push`	`true`	Catches vulnerabilities early
Lifecycle: tagged images	Keep last 10	Balances storage cost vs rollback
Lifecycle: untagged images	Expire after 7 days	Cleans up intermediate layers

ECR Module Reference — Central OIDC roles and policies
ADR-001 — Hybrid management decision

Request an IAM Role

How to add a new IAM role for a service or CI/CD workflow.

Terraform Operations