SAM Template Reference

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:

Parameter	Type	Default	Description
`Stage`	String	`prod`	Deployment stage (`dev`, `staging`, `prod`). Scopes all resource names so multiple environments can coexist in the same AWS account.
`DefaultBedrockModelId`	String	`us.anthropic.claude-sonnet-4-6`	Default Bedrock model used by all agents. Can be overridden per-repo via `.mergewatch.yml`.
`DeploymentMode`	String	`self-hosted`	Deployment mode. Set to `saas` to enable Stripe billing enforcement in the ReviewAgent and deploy the BillingHandler Lambda. `self-hosted` skips all billing checks.
`DashboardBaseUrl`	String	`https://mergewatch.ai`	Base 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:

Resource	Type	Details
WebhookApi	`AWS::ApiGateway::RestApi`	REST API endpoint that receives GitHub webhook POST requests
WebhookHandlerFunction	`AWS::Lambda::Function`	Node.js 20, ARM64, 512 MB, 30s timeout. Validates HMAC signature and invokes ReviewAgent asynchronously.
ReviewAgentFunction	`AWS::Lambda::Function`	Node.js 20, ARM64, 1024 MB, 300s timeout. Runs the multi-agent review pipeline.
InstallationsTable	`AWS::DynamoDB::Table`	On-demand table for GitHub App installation records. GSI on `accountId`.
ReviewsTable	`AWS::DynamoDB::Table`	On-demand table for review history. 90-day TTL. GSI on `createdAt`.
LambdaExecutionRole	`AWS::IAM::Role`	Shared execution role for both Lambda functions with least-privilege permissions.
SSM Parameters	`AWS::SSM::Parameter`	Three SecureString parameters under `/mergewatch/{stage}/` for GitHub App credentials.

Outputs

After deployment, the stack exports these values:

Output	Description
`WebhookUrl`	The URL to set as your GitHub App webhook endpoint (e.g. `https://abc123.execute-api.us-east-1.amazonaws.com/prod`)
`WebhookHandlerArn`	ARN of the WebhookHandler Lambda function
`ReviewAgentArn`	ARN of the ReviewAgent Lambda function
`InstallationsTableName`	Name of the DynamoDB installations table
`ReviewsTableName`	Name 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:

CloudWatch Logs

logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEventsAllows both Lambda functions to write execution logs to CloudWatch.

DynamoDB

dynamodb:GetItem, dynamodb:PutItem, dynamodb:UpdateItem, dynamodb:QueryScoped to the two MergeWatch tables only. No Scan or DeleteItem permissions are granted.

Amazon Bedrock

bedrock:InvokeModelScoped to the model ID specified in the DefaultBedrockModelId parameter. The ReviewAgent uses this to call the multi-agent pipeline.

SSM Parameter Store

ssm:GetParameterScoped to /mergewatch/{stage}/*. Allows Lambda to decrypt and read GitHub App credentials at runtime.

Lambda Invoke

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-6",
  "DeploymentMode=saas",
  "DashboardBaseUrl=https://mergewatch.example.com"
]

sam deploy \
  --stack-name mergewatch-staging \
  --parameter-overrides \
    Stage=staging \
    DefaultBedrockModelId=us.anthropic.claude-sonnet-4-6 \
    DeploymentMode=self-hosted \
    DashboardBaseUrl=https://staging.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.

Overview

Self-Hosting

LLM Providers

Platform Guides

Configuration

GitHub App

Deployment

Dashboard

Managed SaaS

Reference

SAM Template Reference

Parameters

Resources created

Outputs

IAM permissions

Customization

Next steps

Architecture Overview

Self-Hosted Install

​Parameters

​Resources created

​Outputs

​IAM permissions

​Customization

​Next steps

Architecture Overview

Self-Hosted Install

Parameters

Resources created

Outputs

IAM permissions

Customization

Next steps