How to Deploy Static Files to Amazon S3 in CircleCI

The aws-s3 orb wraps aws s3 sync, so a single job uploads your build output to a bucket using credentials from a context.

Import circleci/aws-s3, build your site in one job, persist it to the workspace, then call aws-s3/sync in a deploy job restricted to main.

Steps

• Add the aws-s3 orb and build the static output in a build job.
• Run aws-s3/sync with the local from directory and the to bucket path.
• Restrict the sync to main and pull credentials from a context.

Config

version: 2.1
orbs:
  aws-s3: circleci/aws-s3@4.0.0
jobs:
  build:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - run: npm ci && npm run build
      - persist_to_workspace:
          root: .
          paths: [dist]
  deploy:
    docker:
      - image: cimg/python:3.12
    steps:
      - attach_workspace:
          at: .
      - aws-s3/sync:
          from: dist
          to: 's3://acme-site'
          arguments: '--delete'
workflows:
  ship:
    jobs:
      - build
      - deploy:
          context: aws-prod
          requires: [build]
          filters:
            branches:
              only: main

Gotchas

• The build output lives in a different job, so move it with the workspace; the deploy job starts on a clean container.
• Invalidate your CDN (for example CloudFront) after the sync, or visitors keep seeing cached old files.

Related guides