albertshih.net is a static site generated with Astro, hosted on Amazon S3 with CloudFront in front. This post records the whole architecture and the reasoning behind each choice.
Architecture overview
After a push to GitHub, GitHub Actions gets a temporary role through OIDC and uploads the build output to S3. Visitors are served through CloudFront, and Route 53 and ACM handle the domain and the certificate.
| Component | Purpose | Why I chose it |
|---|---|---|
| Astro | Generates the static pages | Content is mostly Markdown, and the build output is plain HTML |
| S3 (private) | Stores the site files | Static website hosting stays off; only CloudFront can read, through OAC |
| CloudFront | CDN and HTTPS | Global caching; a CloudFront Function handles index.html and the www redirect |
| ACM (us-east-1) | TLS certificate | CloudFront only accepts certificates from us-east-1 |
| Route 53 | DNS | The domain is registered in Route 53 too, with Alias records pointing straight at CloudFront |
| GitHub Actions + OIDC | Automated deployment | No long-lived access keys stored in GitHub |
| Lambda Function URL | GitHub sign-in for the writing admin | Runs only at sign-in, so it costs almost nothing |
Deployment flow
- Push to
main - GitHub Actions exchanges an OIDC token for a temporary IAM role
- After
astro build, upload withaws s3 sync: HTML is not cached, everything else is cached for a long time - Create a CloudFront invalidation
What I learned
Going from nothing to a live site, the time did not go into writing pages. It went into the following pitfalls that only show up on the first deployment.
1. GitHub’s OIDC subject is no longer just repo:owner/repo
After the first push, GitHub Actions failed with Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentity. The role’s trust policy and the OIDC provider’s audience were both correct. The cause turned up in the repository’s OIDC settings: newer accounts default to an “immutable subject”, in the form repo:owner@<owner ID>/repo@<repo ID>:ref:refs/heads/main, so my hard-coded repo:owner/repo:ref:refs/heads/main could never match.
My fix was to switch the trust policy to StringLike and accept both the old format and the format with IDs (wildcards for the ID parts). That way no numbers are hard-coded in the template, renaming or recreating the repo will not break it, and only the main branch of this repository can still obtain the deploy role.
2. Least privilege is “run it, patch it, repeat”
I first wrote a least-privilege policy for my own IAM user, limited by resource name. The very first deployment failed while creating the CloudFront distribution because cloudfront:ListTagsForResource was missing. CloudFormation calls APIs you would not think of while creating resources, so reading the template alone will not give you the full list.
Two side effects worth knowing:
- After a failure the stack sits in
ROLLBACK_COMPLETE, which cannot be updated. You have to delete it and create it again. - An S3 bucket with
Retainsurvives the rollback, so the next deployment leaves you with an extra empty bucket.
My conclusion: least privilege is not something you get right in one go. You let the deployment fail, read the error, add the permission, and repeat until the policy settles. Then you remove the permission once you are done.
3. A blank NoEcho parameter will not be reported by CloudFormation
The GitHub OAuth client secret reaches the Lambda as a NoEcho parameter. I read the secret with read -s, but I ran it in an environment with no keyboard input, so the secret became an empty string, and the stack still reported success. I only found out at sign-in, when GitHub returned The client_id and/or client_secret passed are incorrect.
I checked by reading the Lambda’s environment variables, looking only at the length and format (a GitHub secret is 40 hexadecimal characters) and never printing the value. Two lessons:
- A successful deployment only means the resources were created, not that the configuration is right. You need a check that can verify it.
- Type secrets in your own terminal, not anywhere that gets recorded.
4. Deployment order decides whether visitors see the new site or an unstyled page
Astro’s CSS and JS file names carry a hash. My original flow synced _astro/ with --delete first and uploaded the HTML afterwards. For a while, the old HTML was still in the CloudFront cache but asked for old files that were already deleted, which meant 404s and a page with no styling.
The fixed order: upload the new assets first (without deleting), upload the pages, create the invalidation and wait for it to finish, and only then delete the old assets. This needs one more permission on the deploy role, cloudfront:GetInvalidation, so it can wait for the invalidation.
5. A public Lambda Function URL needs two permissions
The admin’s GitHub sign-in uses a Lambda Function URL (AuthType: NONE). Besides lambda:InvokeFunctionUrl, I added a lambda:InvokeFunction permission restricted to calls “via the Function URL”. With both in the template, the sign-in endpoint returned a normal 302 from the start and never gave me a Forbidden. A lambda:InvokeFunction permission without that restriction would let anyone invoke the function directly, so do not write it that way.
6. Small things you only notice after going live
- Redirects eat the query string: if the CloudFront Function builds the URL from
urialone when doing the www redirect and adding the trailing slash,?utm_source=...disappears. Rebuild it from thequerystringobject and handle parameters that appear more than once. - OAuth scope: the admin originally asked for
repo,user, which is read and write access to every private repository in the account. I dropped the unuseduser. If the repository is private you must keeprepo; only a public repository can usepublic_repo. - Pin third-party scripts: the admin page can reach a token with write access, yet it loaded the CMS from a CDN with a floating version. I pinned the version and added SRI; when you upgrade, you recompute the hash yourself.
- Do not ship unfinished content: scan
dist/in CI and fail the deployment while any bracketed fill-in text or empty social link remains. That is more reliable than remembering. - Keep CloudFormation templates ASCII-only: I put one ”…” character inside the inline Lambda code, and on Windows the AWS CLI reads the file as cp950 and fails with a decode error.
If I did it again
I would decide up front what “deployed” means: not just a green stack, but the home page, /admin, the OAuth endpoint, the www redirect and links with parameters all verified by a single command. This time, each of those checks was added one by one after something broke.