Story-775 functions lane walkthrough publishing

Activate walkthrough auto-publishing

The workflow already knew how to publish walkthroughs. This Story gives it the identity, permissions, and secrets it needs to run without a person copying files by hand.

The mental model: GitHub Actions is the operator, OIDC is the badge, IAM is the door policy, S3 is the shelf, and CloudFront is the public counter. The activation work makes each handoff explicit.

What changed

Identity

GitHub Actions can request AWS credentials only through the account's OIDC provider.

Trust

The publisher role trusts only pramaan-io/pramaan-functions on main.

Permission

The role can put and read walkthrough objects, list the bucket, and invalidate one CloudFront distribution.

Secrets

The workflow gets the role ARN, base URL, and distribution ID from GitHub Actions secrets.

Why OIDC matters

A long-lived AWS key in GitHub is a spare house key: it works, but it can be copied, leaked, and forgotten. OIDC is closer to a front-desk pass. GitHub proves which repo and branch is asking, AWS checks that claim against the role trust policy, and the credentials expire quickly.

The important engineering move is the branch condition. The role is not a general repo robot. It exists for merged walkthrough publishing from refs/heads/main.

What stays out of V1

Slack notification is optional for this activation. Publishing should not fail just because the notification route is not wired yet. That keeps the first slice honest: prove S3 upload, index rebuild, CloudFront invalidation, and public URL resolution before adding more ceremony.

How to verify

  1. Manually dispatch publish-walkthroughs.yml.
  2. Confirm the run uploads the existing walkthrough HTML files as flat keys such as 722.html.
  3. Confirm index.html is rebuilt from the current bucket objects.
  4. Confirm CloudFront invalidates the changed pages and index.
  5. Open https://walkthroughs.pramaan.io/722.html and this Story's 775.html.

Product outcome: after this merges, the next walkthrough HTML file that lands on main publishes itself. The manual aws s3 cp era ends because the workflow now has a safe, narrow production identity.