CI/CD

This repository is deployed as a static site:

GitHub Actions -> build Docusaurus -> sync build/ to S3 -> invalidate CloudFront
                                                          |
                                                          -> Cloudflare Access protects engineering.spwhin.com

The app itself does not implement login. Authentication is enforced in front of CloudFront using Cloudflare Access + GitHub OAuth.

Repositories and workflows

Repo	Purpose	Workflow
spwhin-portal	Docusaurus docs portal	.github/workflows/preview.yml, .github/workflows/deploy.yml

Preview flow

preview.yml runs on pull requests to main:

1. Checks out the repo
2. Installs Node 20
3. Runs npm ci
4. Runs npm run build
5. Comments on the PR when the build succeeds

Production deploy flow

deploy.yml runs on pushes to main and can also be triggered manually with workflow_dispatch.

1. Builds the Docusaurus site
2. Downloads the build artifact in the deploy job
3. Assumes an AWS IAM role using GitHub OIDC
4. Syncs the static output to S3
5. Invalidates CloudFront

AWS resources required

The production portal needs these AWS resources:

Resource	Value	Notes
S3 bucket	engineering.spwhin.com	Stores built static files
ACM certificate	engineering.spwhin.com	Must be issued in us-east-1 for CloudFront
CloudFront distribution	Alias engineering.spwhin.com	Uses the S3 bucket as origin
IAM OIDC role	Example: github-actions-s3-deploy	Trusted by GitHub Actions for this repo

Recommended bucket configuration

• Keep Block Public Access enabled
• Use CloudFront as the only public entrypoint
• Prefer CloudFront Origin Access Control (OAC) over a public bucket policy
• Enable default encryption (AES256 is sufficient for this site)
• Versioning is optional but recommended

GitHub configuration required

This repo needs the following Actions secrets:

Secret	Example	Purpose
AWS_DEPLOY_ROLE_ARN	arn:aws:iam::763832339314:role/github-actions-s3-deploy	IAM role assumed by aws-actions/configure-aws-credentials
CLOUDFRONT_DISTRIBUTION_ID	E123ABC456DEF	Used for cache invalidation after deploy

Optional repo or environment variables:

Variable	Default in workflow	Purpose
AWS_REGION	ap-south-1	AWS region for S3 and STS
S3_BUCKET	engineering.spwhin.com	Static site bucket
SITE_URL	https://engineering.spwhin.com	Deployment summary / environment URL

Configure secrets with GitHub CLI

gh secret set AWS_DEPLOY_ROLE_ARN --repo SPW-HEALTHCARE-INNOVATIONS-Pvt-Ltd/spwhin-portal
gh secret set CLOUDFRONT_DISTRIBUTION_ID --repo SPW-HEALTHCARE-INNOVATIONS-Pvt-Ltd/spwhin-portal

AWS bootstrap checklist

The exact AWS creation commands depend on who has provisioning access, but the resource order should be:

1. Request or import an ACM certificate for engineering.spwhin.com in us-east-1
2. Create the S3 bucket engineering.spwhin.com
3. Create the CloudFront distribution with:
   • alternate domain name engineering.spwhin.com
   • ACM certificate from us-east-1
   • default root object index.html
   • HTTPS redirect enabled
   • OAC attached to the S3 origin
4. Create or update the IAM OIDC role trusted by GitHub Actions for:
   • repo: SPW-HEALTHCARE-INNOVATIONS-Pvt-Ltd/spwhin-portal
   • branch: refs/heads/main
5. Add the GitHub secrets listed above
6. Point DNS for engineering.spwhin.com at the CloudFront distribution
7. Put Cloudflare Access in front of the hostname

OIDC trust policy shape

The GitHub deploy role should trust the GitHub OIDC provider and scope access tightly to this repository and branch.

Example subject:

repo:SPW-HEALTHCARE-INNOVATIONS-Pvt-Ltd/spwhin-portal:ref:refs/heads/main

At minimum, the role needs:

• s3:ListBucket on engineering.spwhin.com
• s3:PutObject, s3:DeleteObject, s3:GetObject on engineering.spwhin.com/*
• cloudfront:CreateInvalidation on the target distribution

Cloudflare handoff

After AWS is ready:

1. Create a proxied DNS record in Cloudflare for engineering.spwhin.com
2. Point it to the CloudFront distribution domain name
3. Follow the GitHub SSO Setup — Cloudflare Access guide
4. Verify that anonymous traffic is blocked before opening access to the team

Validation

Before merging any deployment change, run:

npm run typecheck
npm run build

After merge to main:

1. Check the Deploy portal to S3 and CloudFront workflow
2. Open https://engineering.spwhin.com
3. Confirm the Cloudflare Access login appears
4. Sign in with a GitHub account inside the allowed org
5. Confirm docs pages load and hard refresh succeeds