How merged teaching artifacts become clickable public URLs.
The short version: Story-773 gives PRAMAAN a publishing rail for walkthrough HTML. Engineers keep writing static HTML into docs/walkthroughs. After merge, GitHub Actions assumes an AWS role through OIDC, uploads the HTML to private S3, invalidates CloudFront, rebuilds the index page, and posts to Slack through SNS plus AWS Chatbot.
A walkthrough is only useful if another engineer can read it at the moment they need context. Before this Story, the artifact lived in the repo. That meant cloning, browsing files, and trusting that the reader knew where to look.
The product situation is familiar: a PR explains a backend change, but the best teaching artifact is an HTML page. We want the PR and issue to point at a stable URL, while keeping the publishing path boring, auditable, and cheap.
Important boundary: S3 stores the files, but S3 is not the public website. CloudFront is the public reader. That keeps direct bucket access closed while still letting the team open simple links.
The key design is separation of duties. Provisioning creates the shared AWS rail. Publishing uses that rail after each merge. The workflow does not carry permanent AWS keys; it receives a short-lived identity from GitHub OIDC.
.github/workflows/provision-walkthrough-distribution.yml
Manual operator workflow. It creates the bucket, versioning, CloudFront OAI, distribution, SNS topic, AWS Chatbot Slack route, and the GitHub OIDC publisher role.
.github/workflows/publish-walkthroughs.yml
Automatic publish workflow. It runs on push to main when walkthrough HTML changes, uploads changed files, rebuilds the index, invalidates CloudFront, and posts the Slack message through SNS.
docs/walkthroughs/publishing.md
Operator contract. It names the AWS resources, required GitHub secrets, object key convention, smoke test, and rollback path.
tests/unit/test_walkthrough_distribution_workflows.py
Workflow-shape tests. They make sure later edits do not accidentally make S3 public, reintroduce long-lived AWS keys, skip CloudFront invalidation, or switch Slack delivery to an untracked webhook.
The highest-risk mistake would be publishing by making the S3 bucket public. This implementation avoids that: the bucket permits object reads only to the CloudFront origin access identity. Public readers hit CloudFront.
The second risk is credential drift. The publish workflow uses id-token: write and role-to-assume. That means GitHub gets temporary AWS credentials only when the trusted repo is on main.
The third risk is notification sprawl. The workflow uses SNS because this repo already routes Slack through AWS Chatbot. One channel, one AWS-controlled route, no raw webhook secret in a random workflow.
Check yourself: if a walkthrough URL works, you should be able to explain which component is serving it. The answer should be CloudFront, not direct S3 website hosting.
The code defines the rail, but AWS still has to run it. An operator must dispatch the provisioning workflow with the GitHub OIDC provider ARN and the Slack workspace/channel IDs. Then the repository secrets printed in the summary must be set before the publish workflow can succeed.
Custom DNS is explicitly Phase 2. V1 starts with the CloudFront-assigned domain, and the PR body URL format can move to walkthroughs.pramaan.io once DNS and ACM are ready.