# Deploy a Hugo Site to S3 with CodeBuild

- URL: https://karandeepsingh.ca/posts/deploy-hugo-s3-codebuild/
- Author: Karandeep Singh
- Published: 2021-09-23
- Updated: 2026-02-14
- Tags: s3, aws, codebuild
- Summary: Learn how to deploy a Hugo static site to S3 using AWS CodeBuild with a custom GoLang Docker image and a buildspec.yaml pipeline.

Hugo is one of the fastest static site generators available, and combined with AWS CodeBuild and S3, you get a fully automated deployment pipeline with minimal infrastructure overhead. This guide walks through setting up a Hugo site, configuring CodeBuild, and deploying to S3.

![Fiber optic cables in a server switch panel powering cloud deployments](https://karandeepsingh.ca/images/posts/deploy-hugo-s3-codebuild.jpg)

## Prerequisites

- An active AWS account with permissions for S3, ECR, and CodeBuild
- Hugo installed locally ([installation guide](https://gohugo.io/getting-started/installing/))
- AWS CLI configured with valid credentials
- Git installed and a remote repository (GitHub, Bitbucket, or CodeCommit)

## Create a Hugo Site

Start by scaffolding a new Hugo project and adding a theme:

```bash
hugo new site my-site
cd my-site
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
echo 'theme = "ananke"' >> config.toml
```

Create your first post and verify the site builds locally:

```bash
hugo new posts/my-first-post.md
hugo server -D
```

Once you're satisfied with the local preview, commit your changes:

```bash
git add .
git commit -m "Initial Hugo site setup"
```

## Configure S3 Deployment

In your `config.toml`, set the `baseURL` to your S3-hosted domain or bucket URL:

```toml
baseURL = 'https://your-domain.com/'
```

Hugo has built-in deployment support. Add the deployment target to `config.toml`:

```toml
[deployment]
[[deployment.targets]]
name = "s3"
URL = "s3://your-bucket-name?region=us-east-1"
```

You can also sync manually using the AWS CLI:

```bash
hugo && aws s3 sync public/ s3://your-bucket-name --delete
```

## Create the buildspec.yaml

The `buildspec.yaml` file tells CodeBuild how to build and deploy your Hugo site. Place it in the root of your repository:

```yaml
version: 0.2

env:
  variables:
    HUGO_VERSION: "0.123.0"

phases:
  install:
    commands:
      - wget -q "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit.deb"
      - dpkg -i "hugo_extended_${HUGO_VERSION}_Linux-64bit.deb"
  pre_build:
    commands:
      - echo "Hugo version:" && hugo version
  build:
    commands:
      - hugo --minify
  post_build:
    commands:
      - aws s3 sync public/ s3://${S3_BUCKET} --delete
      - echo "Build completed on $(date)"

artifacts:
  files:
    - '**/*'
  base-directory: public
```

Update `HUGO_VERSION` to match the version you need. Use `hugo_extended` if your theme requires SCSS/SASS processing.

## Set Up CodeBuild

1. **Create a CodeBuild project** in the AWS Console ([docs](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project-console.html)).
2. **Source**: Connect your Git repository (GitHub, Bitbucket, or CodeCommit).
3. **Environment**: Use a managed image (Amazon Linux 2, standard runtime) or a custom Docker image from ECR if you need specific tooling.
4. **Service role**: Ensure the CodeBuild service role has `s3:PutObject`, `s3:DeleteObject`, and `s3:ListBucket` permissions on your target bucket.
5. **Environment variables**: Add `S3_BUCKET` with your bucket name.

## Monitoring and Troubleshooting

**CloudWatch Logs**: CodeBuild streams build logs to CloudWatch automatically. Check these first when a build fails.

**Common issues**:
- **Hugo version mismatch**: Ensure the version in `buildspec.yaml` matches what your theme requires.
- **Permission denied on S3**: Verify the CodeBuild service role has the correct S3 permissions.
- **Theme not found**: If using Git submodules, ensure CodeBuild clones submodules by enabling "Git clone depth" and "Fetch Git submodules" in the source configuration.

**Pre-build debugging**: Add `ls -la` in the `pre_build` phase to verify your source files are present and the working directory is correct.

## Cost Considerations

Running a Hugo site on S3 with CodeBuild is one of the most cost-effective hosting options:

- **S3 static hosting**: Pennies per month for low-to-moderate traffic sites.
- **CodeBuild**: 100 free build minutes per month on the `general1.small` instance. Most Hugo builds complete in under 60 seconds.
- **CloudFront** (optional): Adding a CDN improves performance and provides HTTPS, with a generous free tier of 1TB transfer per month.

Use [AWS Budgets](https://aws.amazon.com/aws-cost-management/aws-budgets/) to set spending alerts and avoid surprises.