--- title: "Deploy to AWS" description: "Deploy to Amazon Web Services from CircleCI: upload to S3, push Docker images to ECR, update ECS services, and deploy applications with AWS CodeDeploy." platform: "Cloud, Server" doc_version: "Server" last_updated: "2026-10-06" --- > For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md). > > For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt). # Deploy to AWS In this how-to guide, you will learn how to configure CircleCI to deploy to Amazon Web Services. ## Introduction This page covers deployment to S3, ECR/ECS (Elastic Container Registry/Elastic Container Service), as well as application deployment using AWS Code Deploy. For more detailed information about the AWS S3, ECS, ECR, and CodeDeploy orbs, refer to the following orb registry pages: * [AWS S3](https://circleci.com/developer/orbs/orb/circleci/aws-s3) * [AWS ECR](https://circleci.com/developer/orbs/orb/circleci/aws-ecr) * [AWS ECS](https://circleci.com/developer/orbs/orb/circleci/aws-ecs) * [AWS CodeDeploy](https://circleci.com/developer/orbs/orb/circleci/aws-code-deploy) In addition to the orb described below, CircleCI has created an AWS convenience image focusing [deployment: `cimg/aws`](https://circleci.com/developer/images/image/cimg/aws). ## Deploy to S3 using the AWS S3 orb For detailed information about the AWS S3 orb, refer to the [CircleCI AWS S3 Orb Reference](https://circleci.com/developer/orbs/orb/circleci/aws-s3) page. This section details the use of the AWS S3 orb and `version: 2.1` configuration for simple deployment, below we will look at the same example without orbs and using `version: 2` configuration. ### 1\. Create IAM user For security best practice, create a new [IAM user](https://aws.amazon.com/iam/details/manage-users/) specifically for CircleCI. ### 2\. Add AWS access keys Add your [AWS access keys](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys) to CircleCI – store your Access Key ID in a variable called `AWS_ACCESS_KEY_ID` and your Secret Access Key in a variable called `AWS_SECRET_ACCESS_KEY`. ### 3\. Deploy using orb Use the orb’s `sync` command to deploy. Note the use of workflows to deploy only if the `build` job passes and the current branch is `main`. Make sure to replace any placeholder versions in the example. ```yaml version: 2.1 orbs: aws-s3: circleci/aws-s3@4.1.0 # use the AWS S3 orb in your configuration workflows: # Define a Workflow running the build job, then the deploy job build-deploy: # Make a workflow to build and deploy your project jobs: - build - deploy: requires: - build # Only run deploy job once the build job has completed filters: pipeline.git.branch == "main" # only run the deploy job on the main branch jobs: # Define the build and deploy jobs build: docker: # Use the Docker executor for the build job - image: # Specify the Docker image to use for the build job steps: - checkout # build job steps omitted for brevity deploy: docker: # Use the Docker executor for the deploy job - image: # Specify the Docker image to use for the deploy job steps: - checkout - aws-s3/sync: from: bucket to: 's3://my-s3-bucket-name/prefix' arguments: | # Optional arguments --acl public-read \ --cache-control "max-age=86400" ``` ## Deploy to S3 without orbs ### 1\. Create IAM user For security best practice, create a new [IAM user](https://aws.amazon.com/iam/details/manage-users/) specifically for CircleCI. ### 2\. Add AWS access keys Add your [AWS access keys](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys) to CircleCI – store your Access Key ID in a variable called `AWS_ACCESS_KEY_ID` and your Secret Access Key in a variable called `AWS_SECRET_ACCESS_KEY`. ### 3\. Create deploy job In your `.circleci/config.yml` file, create a new `deploy` job. In the `deploy` job, add a step to install `awscli` in your primary container. ### 4\. Install the AWS CLI Install `awscli` in your primary container by following the [AWS CLI documentation](https://docs.aws.amazon.com/cli/latest/userguide/installing.html). ### 5\. Deploy with the AWS CLI [Use the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-using.html) to deploy your application to S3 or perform other AWS operations. Note the use of workflows to deploy only if the build job passes and the current branch is `main`. Make sure to replace any placeholder versions in the example. ```yaml version: 2.1 workflows: # Define a Workflow running the build job, then the deploy job build-deploy: jobs: - build - deploy: requires: - build filters: pipeline.git.branch == "main" # only run the deploy job on the main branch jobs: build: docker: # Specify executor for running build job - this example uses a Docker container - image: # Specify docker image to use ... # build job steps omitted for brevity deploy: docker: # Specify executor for running deploy job - image: # Specify docker image to use steps: - run: # Install the AWS CLI if it is not already included in the docker image name: Install awscli command: sudo pip install awscli - run: # Deploy to S3 using the sync command name: Deploy to S3 command: aws s3 sync ``` For a complete list of AWS CLI commands and options, see the [AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/). ## Deploy Docker image to AWS ECR The AWS ECR orb enables you to log into AWS, build, and then push a Docker image to AWS Elastic Container Registry with minimal config. See the [orb registry page](https://circleci.com/developer/orbs/orb/circleci/aws-ecr) for a full list of parameters, jobs, commands and options. Using the `build_and_push_image` job (shown below) requires the following environment variables to be set: `AWS_ECR_ACCOUNT_URL`, `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`. Make sure to replace any placeholder versions in the example. ```yaml version: 2.1 orbs: aws-ecr: circleci/aws-ecr@9.3.7 # Use the AWS ECR orb in your configuration aws-cli: circleci/aws-cli@5.1.2 # Use the AWS CLI orb in your configuration workflows: build_and_push_image: jobs: - aws-ecr/build_and_push_image: # Use the pre-defined `build-and-push-image` job auth: - aws-cli/setup: role_arn: arn:aws:iam::123456789012 dockerfile: path: profile_name: repo: tag: # default - latest ``` ## Update an AWS ECS instance Use the [AWS ECR](https://circleci.com/developer/orbs/orb/circleci/aws-ecr) and [ECS](https://circleci.com/developer/orbs/orb/circleci/aws-ecs) orbs to update an existing AWS ECS instance. Using the `build-and-push-image` job (shown below) requires the following environment variables to be set: `OIDC-USER`, `AWS__DEFAULT_REGION`, `MY_APP_PREFIX`. Make sure to replace any placeholder versions in the example. ```yaml version: '2.1' orbs: aws-cli: circleci/aws-cli@5.1.2 aws-ecr: circleci/aws-ecr@9.3.7 aws-ecs: circleci/aws-ecs@6.0.2 workflows: build-and-deploy: jobs: - aws-ecr/build_and_push_image: auth: - aws-cli/setup: profile_name: OIDC-USER role_arn: arn:aws:iam::123456789012:role/VALID_OIDC_ECR_ROLE profile_name: OIDC-USER repo: MY_APP_PREFIX tag: CIRCLE_SHA1 # This is a built-in environment variable - aws-ecs/deploy_service_update: auth: - aws-cli/setup: profile_name: OIDC-USER role_arn: arn:aws:iam::123456789012:role/VALID_OIDC_ECS_ROLE cluster: MY_APP_PREFIX-cluster container_image_name_updates: container=${MY_APP_PREFIX}-service,tag=${CIRCLE_SHA1} family: MY_APP_PREFIX-service profile_name: OIDC-USER requires: - aws-ecr/build_and_push_image ``` ## AWS CodeDeploy The [AWS CodeDeploy](https://circleci.com/developer/orbs/orb/circleci/aws-code-deploy) orb enables you to run deployments through AWS CodeDeploy. See the example in the developer hub to get started.