Documentation

Overview

Stackform deploys your AWS CDK projects to any AWS account using short-lived OIDC credentials. There are no long-lived keys, no standing access, and full ownership stays with you.

Under the hood, Stackform clones your repo, installs dependencies, synthesizes the CDK app, bootstraps the target account, and deploys all stacks. Logs stream in real-time to the Stackform dashboard.

AWS Account Setup

Stackform uses OIDC federation to securely assume a role in your AWS account. No long-lived credentials are stored. This setup is done once per AWS account.

aws iam create-open-id-connect-provider \
  --url "https://app.stackform.io" \
  --client-id-list "sts.amazonaws.com" \
  --thumbprint-list "6e389d173df252c45ef9ba108af64e32771901b1"

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::YOUR_ACCOUNT_ID:oidc-provider/app.stackform.io"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "app.stackform.io:aud": "sts.amazonaws.com"
        }
      }
    }
  ]
}

aws iam create-role \
  --role-name StackformDeployRole \
  --assume-role-policy-document file://stackform-trust-policy.json \
  --description "Allows Stackform to deploy CDK infrastructure"

aws iam attach-role-policy \
  --role-name StackformDeployRole \
  --policy-arn arn:aws:iam::aws:policy/AdministratorAccess

aws iam get-role --role-name StackformDeployRole \
  --query 'Role.Arn' --output text

Setup via AWS Console

If you prefer the AWS Management Console over the CLI, follow these steps.

CDK Project Requirements

Your CDK project must meet these requirements to deploy through Stackform.

Mandatory files

Example cdk.json

{
  "app": "npx ts-node bin/app.ts"
}

Recommended CDK app pattern

const app = new cdk.App();

const stackName = process.env.STACK_NAME || "my-default-stack";

new MyStack(app, stackName, {
  env: {
    account: process.env.ACCOUNT_ID || process.env.CDK_DEFAULT_ACCOUNT,
    region: process.env.ACCOUNT_REGION || process.env.CDK_DEFAULT_REGION,
  },
});

Package manager support

Container runtime limits

Multi-stack behavior

Stackform deploys all stacks in the synthesized assembly. You cannot selectively deploy individual stacks. Use CDK Stage constructs or conditional logic to control which stacks are synthesized.

Known limitations

• No Docker-in-Docker — DockerImageAsset will fail. Pre-build images and reference them by ECR URI.
• Node.js only— Python CDK projects are not supported in the current runtime.
• No SSM/Secrets Manager at runtime — pass secrets through Stackform environment config.

Environments & Secrets

Configure environment variables and secrets in the Stackform UI. They are injected into your CDK process during synthesis and deployment.

System variables

These are automatically available during synthesis:

SSM Parameter Store secrets

Prefix a variable value with ssm:// to resolve it from SSM Parameter Store before deployment:

DATABASE_URL=ssm:///my-app/prod/database-url

The value is resolved by the deploy-trigger Lambda and injected as a plain-text environment variable. Your CDK code reads it as process.env.DATABASE_URL.

Deploying

Trigger a deployment from the Stackform dashboard or via auto-deploy on Git push.

Deployment flow

Each phase streams real-time logs to the Stackform dashboard. Deployments that fail will have CloudFormation automatically roll back the stack.

Deployment statuses

Auto-Deploy on Git Push

Automatically deploy when code is pushed to a branch. Enable auto-deploy on any environment in the Stackform UI.

How it works

1. Enable Auto-deploy on an environment and select a branch
2. Stackform registers a webhook on your GitHub repository
3. On push to the configured branch, Stackform validates the webhook signature and triggers a deployment
4. Multiple projects sharing the same repo can each deploy to different AWS accounts

Example: multi-project setup

Repo: github.com/acme/infra

  Project A (Org 1)
    Environment "prod"    (branch: main)    -> AWS 111111111111
    Environment "staging" (branch: develop) -> AWS 111111111111

  Project B (Org 2)
    Environment "prod"    (branch: main)    -> AWS 222222222222

Push to main  -> deploys Project A prod + Project B prod
Push to develop -> deploys Project A staging only

Security

• Every webhook payload is validated with SHA-256 HMAC
• Timing-safe comparison prevents timing attacks
• Each organization has its own webhook secret

Redeploy & Rollback

Redeploy from a previously successful deployment without cloning or rebuilding. Useful for fixing drift, retrying, or rolling back to a known-good state.

How redeploy works

1. Every successful deployment archives its cdk.out to S3
2. Redeploy downloads the stored assembly and deploys it directly — no clone, install, or synthesis
3. The engine is automatically selected based on the original deployment duration

Troubleshooting

Pre-deployment Checklist