augint-org (ai-org)

AWS organization automation for Control Tower environments.

augint-org helps manage the parts of a multi-account AWS setup that sit around AWS Control Tower:

• custom OUs such as Workloads
• service-managed CloudFormation StackSets
• custom Service Control Policies
• IAM Identity Center permission assignment
• GitHub Actions OIDC setup
• DNS delegation helpers
• a read-only cost role (billing-cost-reader) for the ai-agency GoHighLevel billing job

It is best understood as post-Control-Tower automation, not as a replacement for AWS Control Tower itself.

Project Health

Reports (API docs, unit tests, coverage, security scans, license compliance) are run artifacts of .github/workflows/publish.yaml. Nothing is published to GitHub Pages (ai-agency docs/standards/github-pages-and-test-reports.md).

What It Does

The current codebase supports these workflows:

• create and inspect organization structure around a Control Tower landing zone
• deploy org-wide StackSets into governed OUs
• attach a custom baseline SCP to Workloads
• create GitHub OIDC trust for both the management account and member accounts
• assign IAM Identity Center permission sets to AWS accounts
• create delegated DNS hosted zones per account
• deploy management-account stacks: the account lifecycle hook, the Forge broker's account-listing role, the read-only billing-cost-reader role, and the AI services opt-out policy

Current Scope

Some parts of the repo are production-ready today, and some are not.

Implemented

• scripts.org_setup: deploy management-account GitHub OIDC and OrgPipelineRole
• scripts.deploy: deploy custom StackSets and the workloads-baseline SCP
• scripts.status: inspect deployed StackSets, OUs, and SCPs
• ai-org sso: assign and list IAM Identity Center access
• ai-org dns delegate: create delegated Route53 zones
• ai-org stackset: inspect and deploy StackSets

Not Implemented Yet

• end-to-end account creation through ai-org account create

The current ai-org account create command is a placeholder that tells you to use AWS Control Tower Account Factory manually.

Architecture

The live organization model this repo is built around looks like this:

Control Tower (AWS Managed)
├── Security OU
│   ├── Audit Account
│   └── Log Archive Account
├── Sandbox OU
└── Workloads OU
    └── Workload accounts managed by this repo's StackSets and SCPs

Important details:

• Security and Sandbox are created by AWS Control Tower.
• Workloads is a custom OU layered on top.
• both Sandbox and Workloads can receive the repo's auto-deployed StackSets.
• the custom workloads-baseline SCP is attached only to Workloads.
• production and staging are currently represented by account naming and OU choice, not by required nested Production and Staging OUs.

What Gets Deployed Automatically

The current StackSet registry auto-deploys these resources to both Workloads and Sandbox:

These StackSets are created but not auto-instanced:

• monitoring
• DNS delegation
• log aggregation
• ACM certificates

Prerequisites

Before using this repo, you should already have:

• an AWS Control Tower landing zone deployed
• IAM Identity Center enabled
• an AWS CLI v2 SSO profile with management-account access
• Python 3.12+
• uv
• a GitHub organization or repository to trust for OIDC

For new organizations, use the AWS Control Tower console first. This repo should be used after the landing zone is healthy.

Install

With uv

uv sync --all-groups

Editable Install

make install

Configuration

You can store personal defaults in ~/.ai-org.env:

AWS_PROFILE=org
DEFAULT_SSO_USER=sam
DEFAULT_PERMISSION_SET=AWSAdministratorAccess
NOTIFICATIONS_EMAIL=alerts@example.com
BUDGETS_MONTHLY_DEFAULT=1000
BUDGETS_ANOMALY_THRESHOLD=100

Or initialize it interactively:

uv run ai-org config init

For org-level deployment, create a project .env:

GH_REPO=augint-org
GH_ACCOUNT=Augmenting-Integrations
AWS_PROFILE=org
NOTIFICATIONS_EMAIL=alerts@example.com
BUDGETS_MONTHLY_DEFAULT=1000
BUDGETS_ANOMALY_THRESHOLD=100

Optional migration settings:

GH_REPO_LEGACY=old-repo-name
GH_ACCOUNT_SECONDARY=secondary-github-org

Recommended Setup Flow

This is the current safe workflow.

1. Launch and validate AWS Control Tower manually

Use the AWS console to:

• enable IAM Identity Center in the Control Tower home Region
• create the landing zone
• create or confirm the audit and log archive accounts
• wait until the landing zone is ACTIVE

2. Create or register the Workloads OU

This repo assumes a top-level Workloads OU exists and is governed.

Create it in AWS Organizations, then register it in AWS Control Tower before deploying custom StackSets.

3. Deploy the management-account pipeline role

uv run python -m scripts.org_setup --profile org

This creates:

• the management-account GitHub OIDC provider
• OrgPipelineRole

4. Deploy org StackSets and SCPs

make deploy

5. Verify

uv run python -m scripts.status --profile org

Account Creation

Current Reality

Account creation is not wired through the public CLI yet.

uv run ai-org account create --help

The current implementation tells you to use AWS Control Tower Account Factory manually.

Recommended Workflow Today

1. Create the account in AWS Control Tower Account Factory.
2. Place it in either Workloads or Sandbox.
3. Wait for Control Tower provisioning to finish.
4. Let StackSets auto-deploy based on OU placement.
5. Use ai-org sso assign to add any additional human admins.
6. Use ai-org dns delegate if the account needs a delegated DNS zone.

GitHub Actions Setup

Member accounts receive GitHubDeployRole through the org-github-oidc StackSet. The repos that may deploy to an account are tags on the account in AWS Organizations:

ai-org account bind 044909224691 --env production --repo Augmenting-Integrations/gotocalendar
ai-org account bind 123456789012 --none      # no GitHub deploy
ai-org account unbind 044909224691 --env production
ai-org account bindings                      # every account and its binding

bind writes the tag github-deploy:<environment> = <owner>/<repo> and sets the trust of GitHubDeployRole at once. The role trusts the subject repo:<owner>/<repo>:environment:<environment> and the same subject in GitHub's immutable-ID form. Only the owners in GITHUB_OWNERS (src/ai_org/core/deploy_bindings.py) can be bound. Run it with the management account profile.

Member accounts also receive SAMDeployRole, which GitHubDeployRole replaces. SAMDeployRole trusts only the OIDC subjects that GITHUB_OIDC_TRUSTED_SUBJECTS in scripts/stackset_registry.py declares for the account. An account with no declaration trusts no subject.

Typical workflow usage:

name: Deploy
on:
  push:
    branches: [main, staging]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read

    steps:
      - uses: actions/checkout@v4

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
          aws-region: us-east-1

      - run: sam deploy

For management-account automation, use the OrgPipelineRole output from scripts.org_setup.

Common Commands

Configuration

uv run ai-org config init
uv run ai-org config show
uv run ai-org config get DEFAULT_SSO_USER
uv run ai-org config list-permission-sets

Accounts

uv run ai-org account list
uv run ai-org account get 123456789012
uv run ai-org account enrollment-status 123456789012

IAM Identity Center

uv run ai-org sso assign 123456789012 --principal founder@example.com
uv run ai-org sso list 123456789012
uv run ai-org sso sync --ou ou-xxxx-workloads --principal founder@example.com

StackSets

uv run ai-org stackset list
uv run ai-org stackset describe org-github-oidc
uv run ai-org stackset status 123456789012 --stackset org-github-oidc
uv run ai-org stackset deploy 123456789012 --stackset org-monitoring

DNS

uv run ai-org dns delegate "My Account Name" --prefix myapp

Scripted Org Operations

make setup
uv run python -m scripts.deploy --profile org
make status
make drift

The infrastructure workflow runs the same drift check after every deploy and nightly at 06:17 UTC. The run fails when the deployed state differs from this repo. The check also runs CloudFormation drift detection on every StackSet instance, so it finds resources that were changed by hand.

Client Billing

Client AWS costs are invoiced from GoHighLevel by the ai-agency daily billing job (infra/sst/ghl-jobs.ts and docs/GHL.md in Augmenting-Integrations/ai-agency). This repo's part is the billing-cost-reader role in the management account (stacks/billing-cost-reader/). It allows ce:GetCostAndUsage, invoicing:ListInvoiceSummaries and organizations:ListAccounts, and trusts only that job's role. The earlier Stripe billing stack and the ai-org billing commands are removed.

AI Services Opt-Out

stacks/ai-services-opt-out/ attaches an AISERVICES_OPT_OUT_POLICY to the organization root. Every current and future account opts out of AWS AI service content use (for example Amazon Transcribe). CloudFormation cannot enable the policy type on the root, so scripts/deploy.py enables it before it deploys the stack. Removing the stack keeps the policy (DeletionPolicy: Retain). Check it from the management account with aws organizations describe-effective-policy --policy-type AISERVICES_OPT_OUT_POLICY --account-id <account>; it must return optOut.

Quota Request Template

A new account starts with a Lambda concurrency quota of 10, so its first deploy can fail. stacks/quota-request-template/ associates a Service Quotas quota request template with the organization. Every account the organization creates after that (Account Factory included) gets a request for 1000 Lambda concurrent executions in us-east-1 (lambda L-B99A9384). CloudFormation has no resource for the template, so a custom resource Lambda manages each entry. Drift fails when the template is not associated or an entry is missing or different. The template does not change accounts that already exist.

Development

make lint
make format
make typecheck
make test
make pre-commit

Known Limitations

• ai-org account create is not implemented yet.
• the safest Control Tower bootstrap path is still manual console work.
• documentation outside this README may still contain older references to Workloads/Production and Workloads/Staging.

Documentation

License

MIT License. See LICENSE.