ECS Preview

What is ECS Preview?

ECS Preview lets projects that do not use Vercel still expose a preview URL for AI Fix pull requests.

Vercel creates previews from Git pushes automatically. ECS/Fargate projects are different: every team has its own VPC, ALB, Route53, IAM, and task definition. QA Note therefore does not provision AWS resources directly. It calls a repository-owned GitHub Actions workflow with a stable contract.

Flow

1. AI Fix pushes code to a qanote/issue-N branch.
2. The QA Note AI Fix workflow dispatches the repository's ECS preview workflow.
3. The ECS preview workflow creates or updates containers, target groups, listener rules, DNS, and the service.
4. The workflow publishes a GitHub deployment status with an environment_url.
5. QA Note receives the GitHub webhook and stores the preview URL on the AI run.

Settings

Open Project Settings → Integrations → ECS Preview and configure:

Vercel Preview and ECS Preview cannot be enabled on the same project. A project must have one preview provider so cleanup, retry, and approval signals converge through one path.

When enabled, QA Note dispatches the workflow with:

action: deploy
branch: qanote/issue-N
ai_run_id: <QA Note run id>
callback_url: <QA Note callback URL>
commit_sha: <implementation commit SHA>

When a preview is deleted or merged from the Preview settings page, QA Note dispatches the same workflow with:

action: destroy
branch: qanote/issue-N
ai_run_id: <QA Note run id>
callback_url: <QA Note callback URL>

AWS Permission Setup

Most ECS Preview failures are IAM issues. Start with a narrow role, run the workflow, and add only the missing permissions.

1. Create the AWS principal for GitHub Actions

GitHub OIDC is recommended.

1. Register the OIDC provider token.actions.githubusercontent.com in AWS IAM.
2. Create a role that only the repository containing the preview workflow can assume.
3. Restrict the trust policy aud to sts.amazonaws.com.
4. Restrict sub to repo:<owner>/<repo>:ref:refs/heads/<default-branch> or the ref pattern you use operationally.
5. If you use long-lived access keys, create a dedicated IAM user and store the key in GitHub secrets, but attach the same least-privilege policy.

2. ECS and task definition permissions

The workflow role needs these permissions scoped to the preview cluster and services:

• ecs:RegisterTaskDefinition
• ecs:DescribeClusters, ecs:DescribeServices, ecs:DescribeTaskDefinition, ecs:DescribeTasks
• ecs:CreateService, ecs:UpdateService, ecs:DeleteService
• ecs:TagResource, ecs:UntagResource

The workflow also needs iam:PassRole for the task execution role and task role used in the task definition. Restrict it to the exact role ARNs and add the iam:PassedToService = ecs-tasks.amazonaws.com condition.

3. ECR permissions

If the workflow builds and pushes images, grant:

• ecr:GetAuthorizationToken
• ecr:BatchCheckLayerAvailability
• ecr:InitiateLayerUpload
• ecr:UploadLayerPart
• ecr:CompleteLayerUpload
• ecr:PutImage
• ecr:BatchGetImage

Scope repository permissions to the ECR repository used for preview images and set a lifecycle policy for old preview images.

4. ALB target group and listener rule permissions

If previews sit behind an ALB, reruns require modify permissions, not just create permissions.

• elasticloadbalancing:CreateTargetGroup, DeleteTargetGroup, DescribeTargetGroups
• elasticloadbalancing:RegisterTargets, DeregisterTargets, DescribeTargetHealth
• elasticloadbalancing:CreateRule, ModifyRule, DeleteRule, DescribeRules
• elasticloadbalancing:DescribeListeners, DescribeLoadBalancers

In the KIAF test, the first deploy created resources, but rerun failed because ModifyRule was missing.

5. Route53 permissions

For automatic preview subdomains, grant these permissions on the hosted zone:

• route53:ChangeResourceRecordSets
• route53:ListResourceRecordSets
• route53:GetHostedZone

Keep the workflow-created record prefix predictable, such as issue-*-preview, and scope permissions to the hosted zone whenever possible.

6. CloudWatch Logs permissions

Fargate tasks need log group and stream access.

• logs:CreateLogGroup, or pre-create the log group
• logs:CreateLogStream
• logs:PutLogEvents
• logs:DescribeLogGroups, logs:DescribeLogStreams

In the KIAF test, the task failed to start because the log group did not exist. For production, pre-create /ecs/<preview-task-family> and set retention to 7-14 days.

7. Cleanup permissions

Do not forget delete permissions for preview cleanup and post-merge cleanup.

• ecs:UpdateService to scale desired count down to 0
• ecs:DeleteService
• elasticloadbalancing:DeleteRule
• elasticloadbalancing:DeleteTargetGroup
• route53:ChangeResourceRecordSets to remove preview records

Workflow Contract

The repository preview workflow must accept at least these workflow_dispatch inputs:

on:
  workflow_dispatch:
    inputs:
      action:
        required: true
        type: string
      branch:
        required: true
        type: string
      ai_run_id:
        required: false
        type: string
      callback_url:
        required: false
        type: string
      commit_sha:
        required: false
        type: string

When the preview is ready, publish a successful GitHub deployment status with the preview URL in environment_url or target_url.

{
  "state": "success",
  "target_url": "https://issue-1-preview.example.com",
  "environment_url": "https://issue-1-preview.example.com",
  "auto_inactive": false
}

On failure, publish failure or error with a useful description. QA Note marks the run as failed and updates the pull request status.

Operations Checklist

• Route53 hosted zone record changes require IAM permission.
• ALB listener rules need create and modify permissions because reruns update existing rules.
• If the task execution role cannot create log groups, create the preview log group ahead of time.
• Each preview runs a Fargate task, so define a cleanup policy.
• Configure ECR lifecycle and CloudWatch Logs retention.

Related

• AI Fix · Auto PR
• Vercel