5 min read

Cloud Docs Hub: A Static Docs Site on S3 with CI/CD

A zero-dependency documentation viewer built with HTML, CSS and vanilla JavaScript, deployed to AWS S3 by GitHub Actions with passwordless OIDC authentication.

  • AWS S3
  • GitHub Actions
  • OIDC
  • IAM
  • HTML5
  • CSS
  • JavaScript
Architecture diagram: a git push to GitHub triggers GitHub Actions, which assumes an AWS IAM role through OIDC and syncs static files to an S3 bucket that visitors load in their browser.

Overview

Cloud Docs Hub is a small documentation site that is hosted on S3 and deploys itself. Merging to main publishes the site, and no long-lived AWS access keys are stored anywhere.

  • Problem: manually uploading a static site to S3 is slow and error-prone, and the usual CI shortcut is to keep AWS access keys in GitHub secrets.
  • Solution: a static viewer with no build step and no dependencies, plus a GitHub Actions workflow that assumes an AWS IAM role through OIDC and syncs the files to S3.
  • Result: a merge to main is live in about 20 seconds, with short-lived credentials and no stored keys.

Features

  • Zero build steps: native HTML5, CSS3 and vanilla JavaScript, so local testing and hosting are simple.
  • Client-side hash routing: moves between documentation topics (for example #index.md and #s3-setup.md) without reloading the page.
  • Light and dark themes: the choice is saved in localStorage, with the system preference as the fallback.
  • Live search: the sidebar links filter as you type.
  • Automated S3 deployment: a GitHub Actions workflow with OIDC authentication syncs the files to the bucket.

Tech stack

Layer Tools Why I chose it
Frontend HTML5, CSS cascade layers, vanilla JavaScript No dependencies and nothing to build or patch
Hosting AWS S3 static website hosting Cheap, durable static file hosting
CI/CD GitHub Actions Runs on every push to main
Authentication OIDC with an IAM role Passwordless access, no stored AWS keys

Architecture

Architecture diagram

The deployment flow, in order:

  1. I work on a feature branch and merge a pull request into main.
  2. The push to main starts the GitHub Actions deploy workflow.
  3. The workflow requests an OIDC token and uses it to assume an IAM role in AWS, which returns short-lived credentials.
  4. aws s3 sync copies the site to the S3 bucket and deletes files that no longer exist in the repository.
  5. Visitors load the site from the bucket’s static website endpoint.

GitHub Actions run where the Sync to S3 job succeeded after a merged pull request

S3 bucket after deployment, showing index.html and the assets folder

Design decisions

  • OIDC instead of access keys: the role trusts GitHub’s identity token, so there is no secret to leak or rotate.
  • No build step: the repository contents are exactly what gets deployed, which keeps the pipeline short.
  • A dedicated bucket: the sync uses --delete, so the bucket mirrors the repository and nothing else lives in it.
  • Public S3 website endpoint: the simplest way to serve a public docs site. The trade-off is plain HTTP and a publicly readable bucket, which is why CloudFront is on the roadmap.

Repository structure

cloud-docs-hub/
├── index.html              Main HTML page shell
├── assets/
│   ├── css/
│   │   └── styles.css      CSS cascade layers: reset, tokens, base, layout, components
│   └── js/
│       └── main.js         Theme switching, hash routing and the Markdown fetcher
├── .github/
│   └── workflows/
│       └── deploy.yml      AWS S3 deployment workflow
└── README.md

Run it locally

Setup

git clone git@github.com:CalebCheptumo/cloud-docs-hub.git
cd cloud-docs-hub

Run

python3 -m http.server 8000

Then open http://localhost:8000 in your browser.

Deploy to AWS

The workflow runs on every push to main. I wrote up the full setup, including the IAM trust policy and the workflow, in Automate S3 Deployments with GitHub Actions and OIDC.

Add these repository secrets under Settings > Secrets and variables > Actions:

Secret Description
AWS_ROLE_ARN ARN of the IAM role that trusts GitHub Actions through OIDC
AWS_S3_BUCKET Name of the target S3 bucket

Security

  • No stored credentials: GitHub Actions exchanges an OIDC token for temporary AWS credentials on each run.
  • Scoped trust policy: the role only accepts tokens whose audience is sts.amazonaws.com and whose subject matches this repository.
  • Least-privilege permissions: the role can only list the bucket and put, get and delete objects in it.
  • Minimal workflow permissions: the job gets id-token: write and read-only access to the repository contents.

Challenges and what I learned

  • GitHub’s immutable subject claims. GitHub now adds permanent numeric owner and repository IDs to the sub claim of new repositories. My first trust policy matched an exact name and failed with Not authorized to perform sts:AssumeRoleWithWebIdentity. Matching with StringLike wildcards fixed it.
  • Two levels of S3 permissions. aws s3 sync needs s3:ListBucket on the bucket itself and the object actions on the objects inside it. Listing only one of the two ARNs makes the sync fail.
  • Lesson: the quickest way to debug OIDC failures is to compare the token’s claims with the trust policy’s conditions.

What’s next

  • Write the documentation pages: getting started, S3 setup, CloudFront and HTTPS, CORS, and the CI/CD pipeline
  • Put CloudFront and an ACM certificate in front of the bucket for HTTPS, and make the bucket private
  • Tighten the trust policy to pin the repository ID and the main branch
  • Generate a table of contents with anchor links from the rendered Markdown