Skip to main content

DEPLOY A STATIC SITE TO AN S3 BUCKET

This guide shows you how to publish a static site to an existing S3 bucket with the @mgreten/aws/s3-site-deploy behavior type. The deploy compares MD5 hashes and uploads only new and changed files. It also deletes bucket objects that are no longer part of the site.

Prerequisites

  • An S3 bucket to deploy to. To create one with Swamp, see Getting started with Amazon S3 in Swamp.
  • AWS credentials that can list, write and delete objects in that bucket, either in the default credential chain or stored in a vault

Pull the extension

swamp extension pull @mgreten/aws/s3-site-deploy --yes

The output looks like:

INF extension·pull: Pulling "@mgreten/aws/s3-site-deploy"@"2026.10.14.1"
INF extension·pull: Identity verified: "@mgreten/aws/s3-site-deploy"@"2026.10.14.1"
INF extension·pull: Pulled "@mgreten/aws/s3-site-deploy"@"2026.10.14.1"
INF extension·pull: Extracted 5 files:

Define the deployment

Create a behavior of type @mgreten/aws/s3-site-deploy named marketing-site. Create and Run a Behavior shows how. Set its global arguments:

globalArguments:
  bucket: example-swamp-site
  region: us-east-1
  skipPaths:
    - Makefile
    - docs
    - CLAUDE.md

bucket is required. List in skipPaths the top-level paths that should not be uploaded. Paths that start with . or _ are always skipped, so they do not need to be listed.

If the credentials are not in the default chain, read them from a vault:

globalArguments:
  bucket: example-swamp-site
  region: us-east-1
  accessKeyId: "${{ vault.get('aws-creds', 'AWS_ACCESS_KEY_ID') }}"
  secretAccessKey: "${{ vault.get('aws-creds', 'AWS_SECRET_ACCESS_KEY') }}"

Run the deployment

swamp behavior run marketing-site deploy

The deploy method uploads new and changed site files to the bucket, removes stale objects, and writes the deployment result metadata to a deployment resource. Run it again after each change to the site. Files that have not changed are not uploaded again.

To look up the deployment resource for a run, see Query and Manage Data.