ECS Preview
Connect AI Fix preview URLs for ECS/Fargate projects
Table of Contents
- What is ECS Preview?
- Flow
- Settings
- AWS Permission Setup
- 1. Create the AWS principal for GitHub Actions
- 2. ECS and task definition permissions
- 3. ECR permissions
- 4. ALB target group and listener rule permissions
- 5. Route53 permissions
- 6. CloudWatch Logs permissions
- 7. Cleanup permissions
- Workflow Contract
- Operations Checklist
- Related
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
- AI Fix pushes code to a
qanote/issue-Nbranch. - The QA Note AI Fix workflow dispatches the repository's ECS preview workflow.
- The ECS preview workflow creates or updates containers, target groups, listener rules, DNS, and the service.
- The workflow publishes a GitHub deployment status with an
environment_url. - QA Note receives the GitHub webhook and stores the preview URL on the AI run.
Settings
Open Project Settings → Integrations → ECS Preview and configure:
| Field | Description |
|---|---|
| Workflow file | File name under .github/workflows/. Default: qanote-ecs-preview.yml |
| Workflow ref | Ref used to run the preview workflow. Use the default branch for production setups |
| Preview URL pattern | Operator note for the expected URL format |
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.
- Register the OIDC provider
token.actions.githubusercontent.comin AWS IAM. - Create a role that only the repository containing the preview workflow can assume.
- Restrict the trust policy
audtosts.amazonaws.com. - Restrict
subtorepo:<owner>/<repo>:ref:refs/heads/<default-branch>or the ref pattern you use operationally. - 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:RegisterTaskDefinitionecs:DescribeClusters,ecs:DescribeServices,ecs:DescribeTaskDefinition,ecs:DescribeTasksecs:CreateService,ecs:UpdateService,ecs:DeleteServiceecs: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:GetAuthorizationTokenecr:BatchCheckLayerAvailabilityecr:InitiateLayerUploadecr:UploadLayerPartecr:CompleteLayerUploadecr:PutImageecr: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,DescribeTargetGroupselasticloadbalancing:RegisterTargets,DeregisterTargets,DescribeTargetHealthelasticloadbalancing:CreateRule,ModifyRule,DeleteRule,DescribeRuleselasticloadbalancing: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:ChangeResourceRecordSetsroute53:ListResourceRecordSetsroute53: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 grouplogs:CreateLogStreamlogs:PutLogEventslogs: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:UpdateServiceto scale desired count down to 0ecs:DeleteServiceelasticloadbalancing:DeleteRuleelasticloadbalancing:DeleteTargetGrouproute53:ChangeResourceRecordSetsto 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.