sam deploy: Usage, Options & Common CI Errors

Deploy your built SAM application to AWS via CloudFormation.

sam deploy packages and deploys the built SAM application as a CloudFormation stack. In CI you run it non-interactively, skipping the changeset confirmation and the guided prompts.

What it does

sam deploy uploads artifacts to S3/ECR, creates a CloudFormation change set, and executes it to create or update the stack. The first interactive sam deploy --guided writes a samconfig.toml with stack name, region, and capabilities; later runs reuse it. CI passes flags directly instead of using guided mode.

Common usage

Terminal

# Interactive first deploy (writes samconfig.toml)
sam deploy --guided

# CI: non-interactive deploy with explicit settings
sam deploy \
  --stack-name myapp \
  --capabilities CAPABILITY_IAM \
  --no-confirm-changeset \
  --no-fail-on-empty-changeset \
  --resolve-s3

Common error in CI: missing capabilities / no deployment bucket

deploy fails with "Requires capabilities : [CAPABILITY_IAM]" (the template creates IAM resources) or "No bucket specified ... run sam deploy --guided or use --resolve-s3". Fix: pass --capabilities CAPABILITY_IAM (or CAPABILITY_NAMED_IAM for named roles), and either commit samconfig.toml or pass --resolve-s3 so SAM manages a deployment bucket. Add --no-confirm-changeset and --no-fail-on-empty-changeset so an unattended run does not prompt or fail when there is nothing to deploy.

Key options

Option	Purpose
--stack-name NAME	Target CloudFormation stack
--capabilities	Acknowledge IAM/named-IAM resources
--no-confirm-changeset	Skip the changeset prompt (CI)
--resolve-s3	Auto-manage the deployment bucket
--no-fail-on-empty-changeset	Succeed when there are no changes