cdk synth: Usage, Options & Common CI Errors
Synthesize your CDK app into CloudFormation templates.
cdk synth executes your CDK app and emits the CloudFormation template(s) it would deploy. It is the fast, credential-light gate to validate that an app synthesizes before any deploy.
What it does
cdk synth runs your app code, resolves constructs into a cloud assembly under cdk.out, and prints the CloudFormation template for a stack (or writes all of them). It does not contact AWS to deploy, though some context lookups (e.g. VPC/AMI) may require credentials unless cached in cdk.context.json.
Common usage
# Synthesize and print a stack template
cdk synth MyStack
# Synthesize all stacks into cdk.out (artifact for deploy)
cdk synth --all
# Quiet mode: write cdk.out without printing YAML
cdk synth --all -qCommon error in CI: context lookup needs credentials
synth fails with "Cannot retrieve value from context provider ... since account/region are not specified" or tries to call AWS for a Vpc.fromLookup. Fix: commit cdk.context.json so lookups are cached and synth runs offline, or supply read credentials plus an explicit env (account/region) on the stack. For a pure offline gate, avoid runtime lookups or pre-populate context with cdk context. Keep cdk.out as the artifact passed to the deploy job for an exact synth→deploy match.
Key options
| Option | Purpose |
|---|---|
| [StackName] | Synthesize a specific stack |
| --all | Synthesize all stacks |
| -q / --quiet | Do not print the template |
| --context KEY=VAL | Pass context values |
| -o / --output DIR | Cloud assembly output directory |
Using this in CI
Cloud CLIs behave differently on a runner than on your laptop. They assume no interactive terminal, no cached credentials, and no browser for device-code flows, so the same command that works locally can hang or fail on a runner.
- Authenticate with a short-lived OIDC token rather than a long-lived static key. GitHub Actions can exchange
id-token: writefor cloud credentials with no stored secret. - Always pass the non-interactive flag. Most cloud CLIs will otherwise prompt and hang until the job times out.
- Pin the CLI version. Cloud CLIs change output formats between minor releases, and any script parsing that output will break silently.
- Set the output format explicitly (
--output json) rather than relying on the default, which can differ by version and configuration profile.