# ADF turns an AWS Organization into a staged multi-account deployment pipeline

> The AWS Deployment Framework is a Python tool that generates CodePipeline pipelines for multi-account, cross-region releases driven by a central configuration file and CloudFormation bootstrapping per organizational unit. It suits platform teams already living in AWS Organizations, and it is not a general CI/CD runner.

**awslabs/aws-deployment-framework** — The AWS Deployment Framework (ADF) is an extensive and flexible framework to manage and deploy resources across multiple AWS accounts and regions based on AWS Organizations.

- Repository: https://github.com/awslabs/aws-deployment-framework
- Stars: 702 · Forks: 235
- Language: Python
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/awslabs-aws-deployment-framework

## The unit of deployment is the account, not the repository

The AWS Deployment Framework is described as an extensive and flexible framework to manage and deploy resources across multiple AWS accounts and regions within an AWS Organization. That framing explains most of its design. A traditional CI/CD system deploys a commit to a runtime. ADF deploys a version of an application or a set of resources to a sequence of AWS accounts, and it does so through the structure defined in AWS Organizations, taking advantage of services such as AWS CodePipeline, AWS CodeBuild and AWS CodeCommit to alleviate the heavy lifting and management compared to a traditional CI/CD setup. The consequence is that the organisation account tree becomes part of your deployment model. You cannot use ADF to ship to a single tenant account in isolation without still deciding how that account relates to the organisation, and the answer to that question shapes everything else.

## Deployment and approval stages live in one configuration file

The central idea of the framework is a single source of truth that describes how a release travels. ADF allows for clearly defined deployment and approval stages which are stored in a centralized configuration file, and the pipeline that CodePipeline runs is generated from that file rather than hand built in the console. A stage is not just a target, it is a gate, so a release can be defined to land in a development account, wait for a human approval, then continue into a testing account and finally into production. This is the piece that most changes day to day work compared to a normal pipeline, because moving a promotion forward becomes an edit to a file in version control and a review, rather than a click on a console button. The user guide exists specifically for using ADF to generate and manage pipelines, and the admin guide covers how to manage and administrate ADF itself, which suggests the framework has a two-audience structure, one for pipeline authors and one for the people who run the platform.

## Moving an account into an OU applies a baseline template

The second mechanism is account based bootstrapping, and it is the one that changes how an organisation is operated. You define an AWS CloudFormation template and assign it to a specific Organization Unit within AWS Organizations. From there, any account you move into this OU will automatically apply this template as its baseline. The operational consequence is that a new account is not a blank slate that someone has to configure by hand. It arrives with whatever the OU template says it should have, which for a platform team usually means the baseline identity, the baseline network hooks, the logging configuration and whatever guardrails the organisation has decided every account gets. The reverse reading is just as important. Because the template is attached to the OU rather than the account, moving an account out of the OU changes its future, and moving one in changes its past. Any mistake in the baseline template therefore propagates to every account that lands in that OU, so the template is the artefact to review hardest.

## The samples show the shape of a real ADF deployment

The samples directory is the fastest way to see what ADF expects a project to look like, and it is broad. There are sample-cdk-app and sample-cdk-bootstrap entries, sample-codebuild-vpc, sample-ec2-java-app-codedeploy, sample-ec2-with-codedeploy, sample-ecr-repository, sample-ecs-cluster, sample-etl-pipeline, sample-expunge-vpc, sample-fargate-node-app, sample-iam, sample-mono-repo, sample-python-cdk-app, sample-serverless-app, sample-service-catalog-product, sample-terraform and sample-vpc. Read that list as a coverage map of the deployment shapes the framework supports: CDK and Terraform, containers on ECS and Fargate, EC2 with CodeDeploy, ECR images, Serverless, a VPC as the unit of promotion, an ETL pipeline, a service catalogue product, and a monorepo where several components move together. The samples guide is offered for a detailed walk through, so the project treats these as documentation in their own right rather than as incidental fixtures.

## Python version and pinned dependencies decide whether it will run

ADF is a Python tool and the packaging constrains the environment more tightly than a typical script. The requirements file pins astroid, aws-sam-cli, boto3, botocore, pyyaml and schema, all at fixed versions, which means the tool assumes a known shape of the AWS SDK and of the SAM CLI. The Makefile makes the Python floor explicit: it requires Python version 3.9 or later, and it goes further, requiring the interpreter to include the tarfile data_filter for safe tar extraction under PEP 706, with a required major version of 3 and a required minor version of 9. That is a detail worth noting because it is the kind of constraint that only shows up on the machine that is not the developer's. The Makefile also carries a version scheme of its own at 2.3.4, with a separate URL for a tagged Makefile, so the build tooling is versioned independently of the framework release.

The pinned requirements are these:

```python
astroid==4.0.4
aws-sam-cli==1.166.2
boto3==1.43.83
botocore==1.43.83
pyyaml~=6.0.3
schema==0.7.8
```

## Releases stopped in 2024 while the master branch kept moving

The version history needs reading carefully, because the two dates say different things. The recent releases are v4.0.0 on 2024-06-11, v3.2.1 on 2024-05-27 and v3.2.0 on 2023-01-24, so the last tagged release is more than two years old. The repository is not archived, and the last push was on 2026-09-20, so the master branch has been receiving work well after the last tag. The default branch is master, and the build status badge points at the ADF CI workflow on that branch. For anyone pinning a dependency, the practical choice is between the v4.0.0 tag, which is documented and reproducible, and the tip of master, which is newer and untagged. The licence is Apache-2.0 with a LICENSE.txt and a NOTICE.md in the tree, which is the permissive licence most organisations expect from an AWS Labs project, though the underlying services it orchestrates carry their own costs that the licence says nothing about.

## The documentation set assumes you already know AWS Organizations

The Quick Start section of the README is a list of documents rather than a set of commands, and that tells you how the project expects to be approached. There is an installation guide for installation steps, an admin guide on guidance how to manage and administrate ADF, a user guide for using ADF to generate and manage pipelines, a technical guide if you want to learn more about the inner workings of ADF, for example in case you want to contribute or build on top of ADF, a samples guide for a detailed walk through of the provided samples, and a multi-organization guide to use ADF in an enterprise-grade setup. That last document matters more than it sounds, because a multi-organization setup means the framework itself is deployed across more than one AWS Organization, which is a different deployment problem from deploying many accounts inside one organisation. The absence of a quick start command is not an omission so much as a signal that this is infrastructure that gets planned, not installed.

## Where ADF is the wrong tool

The boundary is AWS. ADF exists to spread a release across AWS accounts and regions inside AWS Organizations, and it leans on CodePipeline, CodeBuild and CodeCommit to do the building. A team whose workloads live on another cloud has no use for it, and neither does a team with one production account that a plain CodePipeline with a couple of stages would cover. There is also a cost and complexity argument that runs the other way. The framework creates a pipeline per application, and those pipelines, the central configuration file, the OU baseline templates and the bootstrapping accounts are all pieces that exist in your organisation and must be kept working. A team that deploys monthly into two accounts has taken on an operating model that only pays off across many accounts and many promotions. A third limit is the dependency on a specific SAM CLI and SDK generation, because the pinned requirements mean an AWS service change or a botched upgrade can break the generator itself, at which point your pipeline definitions cannot be regenerated even though the running pipelines keep working.

## Conclusion

Adopt ADF when your organisation already runs on AWS Organizations with organizational units and you want account level rollout order and approval gates defined in one configuration file, and pick a plain CodePipeline setup when you have a single account or a few. Verify first which Python version and dependency pins the release expects, because the framework requires Python 3.9 or later and the requirements file pins boto3, aws-sam-cli and schema, and read the installation guide for your target account layout before generating anything, since the pipeline definition and the account bootstrapping template are separate pieces that must agree.

## FAQ

### What is the AWS Deployment Framework?

ADF is a Python framework to manage and deploy resources across multiple AWS accounts and regions within an AWS Organization, using services such as AWS CodePipeline, AWS CodeBuild and AWS CodeCommit. Deployment and approval stages are defined in a centralized configuration file.

### How does account based bootstrapping work in ADF?

You define an AWS CloudFormation template and assign it to a specific Organization Unit within AWS Organizations. Any account you then move into that OU automatically applies this template as its baseline, which means new accounts arrive already configured.

### What Python version does ADF need?

The Makefile requires Python 3.9 or later, and the interpreter must include the tarfile data_filter for safe tar extraction under PEP 706. The requirements file pins astroid, aws-sam-cli, boto3, botocore, pyyaml and schema at fixed versions.

### What kinds of deployment does ADF support out of the box?

The samples cover CDK, Terraform, ECS and Fargate, EC2 with CodeDeploy, ECR repositories, Serverless, VPC promotion, ETL pipelines, service catalogue products and monorepos. The samples guide is offered for a detailed walk through of them.

### What licence is the AWS Deployment Framework under?

It is Apache-2.0 licensed, with a LICENSE.txt and a NOTICE.md in the repository. The last tagged release was v4.0.0 on 2024-06-11, the repository is not archived, and the last push was on 2026-09-20.

## Sources

- [awslabs/aws-deployment-framework on GitHub](https://github.com/awslabs/aws-deployment-framework)
- [Issues](https://github.com/awslabs/aws-deployment-framework/issues)
- [License: Apache-2.0](https://github.com/awslabs/aws-deployment-framework/blob/master/LICENSE)
- [README](https://github.com/awslabs/aws-deployment-framework/blob/master/README.md)
- [Releases](https://github.com/awslabs/aws-deployment-framework/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/awslabs-aws-deployment-framework