AWS ECS / Fargate

AWS ECS with Fargate runs MergeWatch as a serverless container task — no EC2 instances to manage. Choose this option when you want MergeWatch on AWS but need VPC networking, private subnets, or predictable billing instead of the Lambda-based deployment.

Overview

This guide covers creating an ECS service running the MergeWatch container on Fargate, connecting it to an RDS PostgreSQL instance, and exposing the webhook endpoint through an Application Load Balancer (ALB) or API Gateway.

Prerequisites

Install the AWS CLI

aws --version   # requires 2.0.0+
aws sts get-caller-identity   # confirm credentials

Set up networking

You need a VPC with at least two subnets (public for the ALB, private for the Fargate tasks). If you do not have one, use the default VPC or create one with:

aws ec2 create-default-vpc

Gather your GitHub App credentials

Variable	Description
`GITHUB_APP_ID`	Numeric App ID from the GitHub App settings page
`GITHUB_PRIVATE_KEY`	PEM-formatted private key generated for the App
`GITHUB_WEBHOOK_SECRET`	Secret used to validate incoming webhook payloads

Choose an LLM provider

Set LLM_PROVIDER to your preferred provider. If using bedrock, no static API key is needed — attach Bedrock permissions to the ECS task role instead.

Deploy to ECS / Fargate

Create an ECS cluster

aws ecs create-cluster --cluster-name mergewatch

Store secrets in AWS Secrets Manager

aws secretsmanager create-secret \
  --name mergewatch/github-private-key \
  --secret-string "YOUR_PRIVATE_KEY"

aws secretsmanager create-secret \
  --name mergewatch/github-webhook-secret \
  --secret-string "YOUR_WEBHOOK_SECRET"

aws secretsmanager create-secret \
  --name mergewatch/anthropic-api-key \
  --secret-string "YOUR_ANTHROPIC_KEY"

Create the task definition

Create a file called task-definition.json:

{
  "family": "mergewatch",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "executionRoleArn": "arn:aws:iam::YOUR_ACCOUNT:role/ecsTaskExecutionRole",
  "taskRoleArn": "arn:aws:iam::YOUR_ACCOUNT:role/mergewatchTaskRole",
  "containerDefinitions": [
    {
      "name": "mergewatch",
      "image": "ghcr.io/mergewatch/mergewatch:latest",
      "portMappings": [
        { "containerPort": 3000, "protocol": "tcp" }
      ],
      "environment": [
        { "name": "GITHUB_APP_ID", "value": "YOUR_APP_ID" },
        { "name": "LLM_PROVIDER", "value": "anthropic" },
        { "name": "DATABASE_URL", "value": "postgresql://USER:PASSWORD@rds-host:5432/mergewatch" }
      ],
      "secrets": [
        { "name": "GITHUB_PRIVATE_KEY", "valueFrom": "arn:aws:secretsmanager:REGION:ACCOUNT:secret:mergewatch/github-private-key" },
        { "name": "GITHUB_WEBHOOK_SECRET", "valueFrom": "arn:aws:secretsmanager:REGION:ACCOUNT:secret:mergewatch/github-webhook-secret" },
        { "name": "ANTHROPIC_API_KEY", "valueFrom": "arn:aws:secretsmanager:REGION:ACCOUNT:secret:mergewatch/anthropic-api-key" }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/mergewatch",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}

aws ecs register-task-definition --cli-input-json file://task-definition.json

Create the ECS service

aws ecs create-service \
  --cluster mergewatch \
  --service-name mergewatch \
  --task-definition mergewatch \
  --desired-count 1 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-xxx],securityGroups=[sg-xxx],assignPublicIp=ENABLED}"

Set up an Application Load Balancer

Create an ALB in your public subnets and add a target group pointing to the ECS service on port 3000. The ALB provides a stable HTTPS endpoint for GitHub webhooks.

# Create the ALB
aws elbv2 create-load-balancer \
  --name mergewatch-alb \
  --subnets subnet-aaa subnet-bbb \
  --security-groups sg-xxx

# Create a target group
aws elbv2 create-target-group \
  --name mergewatch-tg \
  --protocol HTTP \
  --port 3000 \
  --vpc-id vpc-xxx \
  --target-type ip \
  --health-check-path /webhook

# Create an HTTPS listener (requires an ACM certificate)
aws elbv2 create-listener \
  --load-balancer-arn ALB_ARN \
  --protocol HTTPS \
  --port 443 \
  --certificates CertificateArn=ACM_CERT_ARN \
  --default-actions Type=forward,TargetGroupArn=TG_ARN

If using LLM_PROVIDER=bedrock, you do not need an ANTHROPIC_API_KEY. Instead, attach an IAM policy with bedrock:InvokeModel permission to the ECS task role (mergewatchTaskRole). The SDK uses the task role credentials automatically — no static keys required.

Set up Postgres

Amazon RDS (recommended)

Managed PostgreSQL with automated backups, Multi-AZ failover, and Performance Insights.

Aurora Serverless v2

Auto-scaling PostgreSQL-compatible database. Scales down to 0.5 ACU during idle periods.

Create an RDS instance

aws rds create-db-instance \
  --db-instance-identifier mergewatch-db \
  --db-instance-class db.t4g.micro \
  --engine postgres \
  --engine-version 15 \
  --master-username mergewatch \
  --master-user-password YOUR_DB_PASSWORD \
  --allocated-storage 20 \
  --vpc-security-group-ids sg-xxx

Create the database

psql -h mergewatch-db.xxx.us-east-1.rds.amazonaws.com \
  -U mergewatch -c "CREATE DATABASE mergewatch;"

Update the DATABASE_URL in your task definition to point to the RDS endpoint.

Place the RDS instance in the same VPC and security group as the Fargate tasks. Do not expose the database to the public internet.

Configure the webhook URL

Set the webhook URL on your GitHub App to the ALB DNS name (or your custom domain) followed by /webhook:

https://mergewatch-alb-123456.us-east-1.elb.amazonaws.com/webhook

If you use API Gateway instead of an ALB, the URL will look like:

https://abc123.execute-api.us-east-1.amazonaws.com/webhook

Next steps

Configure review behavior

Tune sensitivity, ignored paths, and review focus areas.

Environment variables

Full list of supported environment variables.

Troubleshooting

Common issues and how to fix them.

Upgrading

How to update MergeWatch to the latest version.

Overview

Self-Hosting

LLM Providers

Platform Guides

Configuration

GitHub App

Deployment

Dashboard

Managed SaaS

Reference

Overview

Prerequisites

Deploy to ECS / Fargate

Set up Postgres

Amazon RDS (recommended)

Aurora Serverless v2

Configure the webhook URL

Next steps

Configure review behavior

Environment variables

Troubleshooting

Upgrading

​Overview

​Prerequisites

​Deploy to ECS / Fargate

​Set up Postgres

Amazon RDS (recommended)

Aurora Serverless v2

​Configure the webhook URL

​Next steps

Configure review behavior

Environment variables

Troubleshooting

Upgrading

Overview

Prerequisites

Deploy to ECS / Fargate

Set up Postgres

Configure the webhook URL

Next steps