From: davecramer (@davecramer) <noreply+davecramer@github.com>
To: postgresql-interfaces/psqlodbc <noreply+postgresql-interfaces-psqlodbc@github.com>
Subject: [postgresql-interfaces/psqlodbc] PR #236: Document how to release the website
Date: Wed, 04 Nov 2026 18:31:33 +0000
Message-ID: <gh-postgresql-interfaces-psqlodbc-236@github.com> (raw)
Adds `website/RELEASING.md`, which explains how to publish https://odbc.postgresql.org/. Merging to `main` doesn't publish the site.
It covers:
- The release steps: merge to `main`, point `www-release` at the commit, run the `Deploy Website` workflow, then check `deploy-info.json` on the live site.
- When to release: after website changes, and after each driver release, because the changelog page is built from `Changelog.md`.
- What a deploy does, step by step.
- How to roll back.
- Who owns the infrastructure, and what to send PostgreSQL infrastructure if the deploy fails with `Not authorized to perform sts:AssumeRoleWithWebIdentity`.
The steps used to be in the comment at the top of `docs-deploy.yml`. That comment now points to the new file and keeps only the list of repository variables, so the process is described in one place. `website/README.md` links to the new file too.
actionlint passes on `docs-deploy.yml`.
Assisted-By: Claude
inline patch 1: .github/workflows/docs-deploy.yml, website/README.md, website/RELEASING.md (+67/-13 lines) download inline-1.patchdiff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.ymlindex 0b397134..0165b419 100644--- a/.github/workflows/docs-deploy.yml+++ b/.github/workflows/docs-deploy.yml@@ -1,18 +1,8 @@
name: Deploy Website
-# Builds the website with docs.yml and deploys it to https://odbc.postgresql.org/.-# The deploy runs only from the www-release branch. After a release, update-# www-release to the commit to deploy and start the deploy on it:-#-# gh workflow run docs-deploy.yml -R postgresql-interfaces/psqlodbc --ref www-release-#-# The deploy uploads the site to the root of the S3 bucket, then deletes the-# files in the bucket that are no longer in the site, then uploads-# /deploy-info.json with metadata about the deployment, and then invalidates-# the CloudFront cache. Each deploy replaces the previous one and no earlier-# version is kept. To roll back, set www-release back to an earlier commit and-# start the deploy again. A run on any other branch fails with an error before-# it builds the site.+# Builds the website with docs.yml and deploys it to https://odbc.postgresql.org/,+# only from the www-release branch. website/RELEASING.md describes how to+# release, roll back, and what each step below does.
#
# The workflow reads these repository variables:
#
diff --git a/website/README.md b/website/README.mdindex 277d65e3..f8510e5a 100644--- a/website/README.md+++ b/website/README.md@@ -19,3 +19,7 @@ hugo --minify # builds the site into public/
- The images and `.reg` files come from `docs/`, which the Windows installer and the source tarball also ship.
Pages that moved keep their old addresses through `aliases` in their front matter, so a link such as `/docs/config.html` redirects to `/docs/configuration/`.
++## Releasing++Merging to `main` does not publish the site. [RELEASING.md](RELEASING.md) describes how to release it to https://odbc.postgresql.org/.diff --git a/website/RELEASING.md b/website/RELEASING.mdnew file mode 100644index 00000000..c958974d--- /dev/null+++ b/website/RELEASING.md@@ -0,0 +1,60 @@+# Releasing the website++https://odbc.postgresql.org/ is served by CloudFront from an S3 bucket. The `Deploy Website` workflow (`.github/workflows/docs-deploy.yml`) builds the site in `website/` and uploads it. It deploys only from the `www-release` branch, so a change merged to `main` is not published until someone releases it.++Release the website after merging changes under `website/`, and after each driver release, because the changelog page is built from `Changelog.md`.++## Steps++1. **Merge the changes to `main`.** On a pull request, the `docs` workflow builds the site and lints the two workflows. It runs when the pull request changes `website/`, `Changelog.md` or `docs/`.++2. **Point `www-release` at the commit to publish,** normally the tip of `main`:++ ```sh+ git fetch origin+ git push origin origin/main:refs/heads/www-release+ ```++ The push fails if `www-release` has commits that `main` doesn't. That only happens after a rollback, described below; use `--force` then.++3. **Start the deploy and wait for it:**++ ```sh+ gh workflow run docs-deploy.yml -R postgresql-interfaces/psqlodbc --ref www-release+ gh run watch -R postgresql-interfaces/psqlodbc \+ "$(gh run list -R postgresql-interfaces/psqlodbc --workflow docs-deploy.yml --branch www-release --limit 1 --json databaseId --jq '.[0].databaseId')"+ ```++4. **Check the live site.** https://odbc.postgresql.org/deploy-info.json shows the commit, the driver version from `configure.ac`, the time and the run ID of the deploy that is live:++ ```sh+ curl -s https://odbc.postgresql.org/deploy-info.json+ ```++ CloudFront's cache is cleared at the end of each deploy, so the new pages show straight away.++## What a deploy does++1. Checks that the run is on `www-release`. A run on any other branch fails before it builds anything.+2. Builds the site with the Hugo version that `.github/workflows/docs.yml` pins.+3. Uploads the site to the root of the bucket.+4. Deletes the files in the bucket that are no longer in the site, after the upload, so that a page that moved stays available while the new files upload.+5. Uploads `/deploy-info.json`.+6. Invalidates the CloudFront cache.++Each deploy replaces the previous one, and the bucket keeps no earlier version.++## Rolling back++Point `www-release` at an earlier commit and deploy again:++```sh+git push --force origin <commit>:refs/heads/www-release+gh workflow run docs-deploy.yml -R postgresql-interfaces/psqlodbc --ref www-release+```++## Infrastructure++PostgreSQL infrastructure owns the AWS account that hosts the site, and the `postgresql.org` DNS. The workflow signs in to AWS through GitHub OIDC, with no stored keys. It reads the role, region, bucket and distribution from repository variables, listed at the top of `.github/workflows/docs-deploy.yml`.++If the deploy fails at "Configure AWS credentials" with `Not authorized to perform sts:AssumeRoleWithWebIdentity`, the role's trust policy does not accept the token. The token's subject is `repo:postgresql-interfaces/psqlodbc:ref:refs/heads/www-release` and its audience is `sts.amazonaws.com`. Ask PostgreSQL infrastructure to check the trust policy.