Skip to main content
This page is for the MergeWatch SaaS deployment only. If you are self-hosting, you do not need SAM. The self-hosted deployment uses Docker and does not involve AWS Lambda or CloudFormation. See Self-Hosting Install instead.
The MergeWatch SAM template (infra/template.yaml) defines all AWS resources required to run the pipeline. It deploys with a single command: 
sam build && sam deploy
The project uses a scripts/deploy.sh wrapper around sam build && sam deploy — invoke it with pnpm run deploy:dev / deploy:staging / deploy from the mergewatch.ai repo. You only need to invoke SAM directly if you are customizing deployment flags.

​
Parameters

The template accepts four parameters that control the deployment:
ParameterTypeDefaultDescription
StageStringprodDeployment stage (dev, staging, prod). Scopes all resource names so multiple environments can coexist in the same AWS account.
DefaultBedrockModelIdStringus.anthropic.claude-sonnet-4-20250514-v1:0Default Bedrock model used by all agents. Can be overridden per-repo via .mergewatch.yml.
DeploymentModeStringself-hostedDeployment mode. Set to saas to enable Stripe billing enforcement in the ReviewAgent and deploy the BillingHandler Lambda. self-hosted skips all billing checks.
DashboardBaseUrlStringhttps://mergewatch.aiBase URL used in PR comment links that point back to the MergeWatch dashboard.
For self-hosted deployments, set DashboardBaseUrl to your own domain if you are running the dashboard separately, or leave the default if you only use GitHub for viewing results.

​
Resources created

The template creates the following AWS resources:
ResourceTypeDetails
WebhookApiAWS::ApiGateway::RestApiREST API endpoint that receives GitHub webhook POST requests
WebhookHandlerFunctionAWS::Lambda::FunctionNode.js 20, ARM64, 512 MB, 30s timeout. Validates HMAC signature and invokes ReviewAgent asynchronously.
ReviewAgentFunctionAWS::Lambda::FunctionNode.js 20, ARM64, 1024 MB, 300s timeout. Runs the multi-agent review pipeline.
InstallationsTableAWS::DynamoDB::TableOn-demand table for GitHub App installation records. GSI on accountId.
ReviewsTableAWS::DynamoDB::TableOn-demand table for review history. 90-day TTL. GSI on createdAt.
LambdaExecutionRoleAWS::IAM::RoleShared execution role for both Lambda functions with least-privilege permissions.
SSM ParametersAWS::SSM::ParameterThree SecureString parameters under /mergewatch/{stage}/ for GitHub App credentials.

​
Outputs

After deployment, the stack exports these values:
OutputDescription
WebhookUrlThe URL to set as your GitHub App webhook endpoint (e.g. https://abc123.execute-api.us-east-1.amazonaws.com/prod)
WebhookHandlerArnARN of the WebhookHandler Lambda function
ReviewAgentArnARN of the ReviewAgent Lambda function
InstallationsTableNameName of the DynamoDB installations table
ReviewsTableNameName of the DynamoDB reviews table
You can retrieve outputs at any time with: 
aws cloudformation describe-stacks \
  --stack-name mergewatch-prod \
  --query "Stacks[0].Outputs" \
  --output table

​
IAM permissions

The Lambda execution role follows least-privilege principles. It includes the following permissions:
logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEventsAllows both Lambda functions to write execution logs to CloudWatch.
dynamodb:GetItem, dynamodb:PutItem, dynamodb:UpdateItem, dynamodb:QueryScoped to the two MergeWatch tables only. No Scan or DeleteItem permissions are granted.
bedrock:InvokeModelScoped to the model ID specified in the DefaultBedrockModelId parameter. The ReviewAgent uses this to call the multi-agent pipeline.
ssm:GetParameterScoped to /mergewatch/{stage}/*. Allows Lambda to decrypt and read GitHub App credentials at runtime.
lambda:InvokeFunctionScoped to the ReviewAgent function ARN. WebhookHandler uses this to invoke ReviewAgent asynchronously (InvocationType.Event).
Do not attach broader permissions (e.g. bedrock:* or dynamodb:*) to the execution role. The template is scoped intentionally — widening permissions increases your blast radius if the role is ever compromised.

​
Customization

You can override template parameters in two ways: 
version = 0.1

[prod.deploy.parameters]
stack_name = "mergewatch-prod"
resolve_s3 = true
capabilities = "CAPABILITY_IAM"
parameter_overrides = [
  "Stage=prod",
  "DefaultBedrockModelId=us.anthropic.claude-sonnet-4-20250514-v1:0",
  "DeploymentMode=saas",
  "DashboardBaseUrl=https://mergewatch.example.com"
]
For the full list of sam deploy options, see the AWS SAM CLI reference.

​
Next steps

Architecture Overview

Understand how the components connect end-to-end.

Self-Hosted Install

Deploy MergeWatch on your own infrastructure with Docker.