pg.ddx.io  GitHub: postgresql-interfaces/psqlodbc (issues + PRs as email threads)  
help / color / mirror / Atom feed
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.yml index 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.md index 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.md new file mode 100644 index 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.

view thread (3+ messages)  latest in thread

Message-ID: <gh-postgresql-interfaces-psqlodbc-236@github.com>
Permalink:  ../gh-postgresql-interfaces-psqlodbc-236@github.com/

 ·  · 


This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox