Install

Overview

Get from zero to deployed infrastructure with the provisioning helper. This guide walks you through prerequisites, scaffolding, and deploying the OIDC bootstrap stack.

Prerequisites

1. Fork and clone the repository

Click the green "Use this template" button to create your repository, then clone it:

git clone https://github.com/YOUR-USERNAME/YOUR-REPO-NAME
cd YOUR-REPO-NAME

2. Install tooling

Install the Rain CLI and Python dependencies:

# macOS
brew install rain

# Install Python dependencies
pip install -r requirements.txt

For other platforms, download Rain from the releases page. See the Rain reference for usage.

3. Run the provisioning helper

The script scaffolds a deployment workflow and parameter folder for your target environment:

./scripts/provision-repo.sh

When prompted, supply:

• GitHub repository slug (e.g., my-org/platform-infra)
• Environment name (test, staging, or production)

The script creates:

Edit the generated parameter file so SubjectClaimFilters matches your repository.

4. Configure AWS credentials

Ensure your AWS CLI profile can assume an administrative role in the target account:

# Verify authentication
aws sts get-caller-identity

# Or use Granted
assume my-profile

5. Validate templates

Run validation before deploying:

# Run Checkov security scanning
./scripts/validate-templates.sh

# Run cfn-lint for template syntax validation
cfn-lint templates/*.yml

The validation script runs Checkov locally. Run cfn-lint separately for template syntax validation. Both tools run automatically in the CI/CD workflow. See the Checkov reference for tuning results.

Tip: Install the CloudFormation Snippets VS Code extension for resource autocompletion.

6. Deploy the bootstrap stack

Deploy the OIDC provider template so GitHub Actions can assume roles in your account:

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

Replace test with your environment name. The script pairs each template in templates/ with its matching parameter file.

Learn more: How to deploy a CloudFormation template

7. Configure GitHub repository variables

In your GitHub repository, go to Settings → Secrets and variables → Actions → Variables and add:

Create one <ENV>_AWS_ACCOUNT_ID variable per environment.

8. Push and verify

Commit and push to trigger the workflow:

git add .
git commit -m "Initial setup"
git push origin main

The workflow deploys using OIDC. Add more environments by re-running provision-repo.sh or copying an existing workflow.

Next steps

• Local Development - Day-to-day commands
• Environments - Multi-environment setup
• CI/CD Workflows - Deployment automation