Keep a living infrastructure reference page in Notion

Every Monday at 8am, rebuild our living infrastructure reference page in Notion using the current state of HCP Terraform, so engineers stop asking in chat what the current database hostname, load balancer address, or bucket name is. Use a cron trigger. When setting this up, ask me for our HCP Terraform organization name, the Notion page to write to, and the Slack channel that should hear about changes.

Start with HCP Terraform's List Workspaces to enumerate every workspace in the organization, paging until you have all of them. For each workspace, pull its published output values with Get Current Workspace Outputs. Where you need the underlying state version detail instead, fall back to List State Version Outputs. Also use Show Current State Version to record when each workspace was last applied, so readers can judge how fresh the values are.

Redaction is the most important rule here. Any output that HCP Terraform marks as sensitive must be listed by name only, with its value redacted, for example "database_password (sensitive, value redacted)". Never write a sensitive value into Notion or Slack, even when the API returns it to you. If you are unsure whether an output is sensitive, treat it as sensitive and redact it.

Organize everything into one clean markdown page. Group workspaces by environment (production, staging, dev), inferring the environment from the workspace name or its tags, and put anything genuinely ambiguous into a separate "Other" group rather than guessing wrong. Within each workspace, show when it was last applied, and write a short plain-language description of what each output actually is, for example "Primary Postgres hostname for the checkout service" rather than dumping raw key and value pairs. The reader is an engineer who wants an answer in five seconds, not a copy of the state file.

Before you overwrite anything, read the existing page with Notion's Retrieve Page as Markdown so you have last week's values to compare against. Then write the new version with Notion's Update Page Content as Markdown, using the replace strategy so the page stays a living document rather than an ever-growing append log. Always write to the same page. Include a line at the top saying when the page was last rebuilt.

Finally, compare this week's values against what was on the page before and send a Slack message with slackbot's Send a Message summarizing only what changed: workspaces that are new, workspaces that have disappeared, and outputs whose values moved. Name the workspace and the output for each change, and keep it short enough to read on a phone. For a sensitive output, say that its value changed without revealing the old or new value. If nothing changed at all, do not post to Slack. Silence is the correct output for a quiet week, and it is what keeps people reading the message when it does arrive.