Install

Install prerequisites, scaffold environment defaults, and deploy the AWS CloudFormation Starter Kit bootstrap stack.

Prerequisites

  • Python 3.9 or newer plus pip
  • AWS CLI authenticated against the accounts you will deploy into
  • Homebrew (macOS) or another package manager that can install Rain (see the Rain reference for supported workflows)
  • jq, curl, and unzip available in your shell (Rain install script relies on them)
  • Optional but recommended: an AWS profile configured with short-lived credentials

1) Fork and clone the repository

git clone https://github.com/towardsthecloud/aws-cloudformation-starter-kit my-cloudformation-foundation
cd my-cloudformation-foundation

If you fork the repository, point origin to your fork before you continue.

2) Install tooling

Install the Rain CLI and Python dependencies used by the helper scripts:

brew install rain
pip install -r requirements.txt

If you are not on macOS, download the Rain binary from the releases page and place it on your PATH. Refer back to the Rain reference for common commands once installation finishes.

3) Run the provisioning helper

./scripts/provision-repo.sh scaffolds a deployment workflow and parameter folder for a target environment. When prompted, supply the GitHub repository slug (for example my-org/platform-infra) and choose the environment you want to enable first (test, staging, or production). The script will produce:

  • .github/workflows/cloudformation-deploy-<environment>.yml
  • parameters/<environment>/oidc-provider.yml
./scripts/provision-repo.sh

Edit the generated parameter file so SubjectClaimFilters matches the repository that will trigger deployments.

4) Configure AWS credentials locally

Ensure the AWS CLI profile you use can assume an administrative role in the target account. A quick smoke test is running aws sts get-caller-identity to confirm you are authenticated before deploying.

5) Validate templates before the first deploy

Run the bundled validation script to execute Checkov (and any other configured scanners) locally. This mirrors the security checks that run in CI and helps you fix issues before the pipeline rejects them. Need a deeper pipeline example? Check our walkthrough on validating CloudFormation templates with CodePipeline.

./scripts/validate-templates.sh

If the script installs Checkov for you, re-run it after installation to ensure the scan passes. Learn more about tuning results in the Checkov reference.

6) Deploy the bootstrap stack with Rain

Deploy the OIDC provider template so GitHub Actions can assume roles in your account. Pass the environment you scaffolded in step 3 via the -e flag so the script picks the correct parameter file.

./scripts/deploy-templates.sh -e test

Replace test with any other environment folder you created. The script loops through every template in templates/, pairing each one with a parameter file that shares the same base name. Explore additional deployment patterns in the Rain reference.

7) Configure GitHub repository variables

In your GitHub repository, add the following variables under Settings → Secrets and variables → Actions → Variables:

  • AWS_REGION: the region Rain should target (for example eu-west-1)
  • <ENV>_AWS_ACCOUNT_ID: one variable per environment (for example TEST_AWS_ACCOUNT_ID), matching the account ID that owns the CloudFormation stacks

Commit the generated workflow and parameter files, push to main, and watch the workflow deploy using OIDC. When you add more environments, re-run provision-repo.sh or copy an existing workflow and adjust the variables.

Next stop: Guides > Local Development walks through the daily commands you will run while iterating on templates.

← OverviewConfiguration →