Hugo Site CI CD Deployment Guide (GitHub Actions + AWS)

GitHub Repository
        |
        v
GitHub Actions
        |
        v
S3 Bucket (Private)
        |
        v
CloudFront Distribution
        |
        v
CloudFront Function
(Index.html Rewrite)
        |
        v
notes.chintanspace.com

hugo

tree public

public
├── index.html
├── aws
│   └── fargate
│       └── index.html
├── hugo
│   └── setup-hugo
│       └── index.html

baseURL = "https://notes.chintanspace.com/"
title = "Alok's Notes"
locale = "en-us"

[module]
[[module.imports]]
path = "github.com/google/docsy"

[params]
copyright = "Alok Modak"

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

git init

git add .

git commit -m "Initial commit"

git branch -M main

git remote add origin https://github.com/<user>/<repo>.git

git push -u origin main

AWS Console
→ S3
→ Create Bucket

notes-prod-bucket

General Purpose

ACLs Disabled (Recommended)
Bucket owner enforced

Keep all enabled

Enabled

SSE-S3

CloudFront
→ Create Distribution

notes-prod-bucket.s3.us-east-1.amazonaws.com

Origin Access Control (OAC)

index.html

{
  "Version": "2008-10-17",
  "Statement": [
    {
      "Sid": "AllowCloudFrontServicePrincipal",
      "Effect": "Allow",
      "Principal": {
        "Service": "cloudfront.amazonaws.com"
      },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::notes-prod-bucket/*",
      "Condition": {
        "StringEquals": {
          "AWS:SourceArn": "arn:aws:cloudfront::<ACCOUNT_ID>:distribution/<DISTRIBUTION_ID>"
        }
      }
    }
  ]
}

AccessDenied

/docs/aws/fargate/

/docs/aws/fargate/index.html

CloudFront
→ Functions
→ Create Function

rewrite-index

function handler(event) {
    var request = event.request;
    var uri = request.uri;

    if (uri.endsWith('/')) {
        request.uri += 'index.html';
    } else if (!uri.includes('.')) {
        request.uri += '/index.html';
    }

    return request;
}

CloudFront
→ Distribution
→ Behaviors
→ Edit

Viewer Request
→ rewrite-index

us-east-1

Certificate Manager
(us-east-1)
→ Request Certificate

notes.chintanspace.com

DNS Validation

Create records in Route53

Status = Issued

Route53
→ Hosted Zone
→ chintanspace.com

notes

A

Yes

de81eyupvfzho.cloudfront.net

CloudFront
→ Distribution
→ General
→ Edit

notes.chintanspace.com

notes.chintanspace.com

SNI Only

IAM
→ Identity Providers
→ Add Provider

OpenID Connect

https://token.actions.githubusercontent.com

sts.amazonaws.com

IAM
→ Roles
→ Create Role

Web Identity

token.actions.githubusercontent.com

sts.amazonaws.com

GitHubNotesDeployRole

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:<github-user>/<repo>:*"
        }
      }
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:s3:::notes-prod-bucket",
        "arn:aws:s3:::notes-prod-bucket/*"
      ]
    },
    {
      "Action": [
        "cloudfront:CreateInvalidation"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}

GitHub
→ Repository
→ Settings
→ Secrets and Variables
→ Actions

.github/workflows/deploy-notes.yml

Checkout Repository

Setup Go

Setup Hugo

Setup Node.js

Install Dependencies

hugo mod tidy

hugo

Configure AWS Credentials (OIDC)

aws s3 sync public/ s3://bucket --delete

aws cloudfront create-invalidation --paths "/*"

https://notes.chintanspace.com

https://notes.chintanspace.com/docs/aws/fargate/
https://notes.chintanspace.com/docs/hugo/setup-hugo/

CloudFront → S3
cannot resolve
directory URLs

CloudFront Function
rewrite-index

IAM Identity Provider exists

permissions:
  id-token: write

Configure AWS Credentials
step not executed

uses: aws-actions/configure-aws-credentials@v4

node-version: '22'

bad option: --permission

GitHub Repository
        |
        v
GitHub Actions
        |
        v
Private S3 Bucket
        |
        v
CloudFront Distribution
        |
        v
CloudFront Function
(Index Rewrite)
        |
        v
ACM Certificate
        |
        v
Route53 Alias
        |
        v
notes.chintanspace.com