From 14d4a13b5fd37cced08c86f07cc579cacea1a4ac Mon Sep 17 00:00:00 2001 From: jamesbeedy Date: Sun, 6 Sep 2026 22:03:15 +0000 Subject: [PATCH] fix(ci): fetch tags so a dispatched docs deploy renders a real version The navbar version badge comes from getProjectVersion() in @vantagecompute/docusaurus-theme, which shells out to `git describe --tags --always`. This workflow checked out at the default depth of 1. That is fine for the tag trigger, which is every deploy this repo has run so far: checkout resolves refs/tags/vX.Y.Z, so the tag describe needs is the very ref checked out, and the live site's badge correctly reads v0.1.6 today. It is not fine for workflow_dispatch. That runs against a branch, and checkout fetches branches with --no-tags, so the clone carries no tags at all and describe falls through to its `--always` case. Replicating what checkout actually runs: git init && git remote add origin git fetch --no-tags --depth=1 origin df7388b # main git describe --tags --always -> df7388b So the first dispatched deploy would have quietly replaced the version in the published header with a commit hash. The build succeeds and the site renders, so nothing would have caught it but someone reading the header. Every other Vantage docs spoke already sets fetch-depth: 0. This one was the exception. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/deploy-docs.yml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 1dcff11..bf1c96d 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -45,7 +45,27 @@ jobs: # The pydoc plugin comes from npm, so there is no submodule to check out and no # transport rewriting to do. It used to be vendored as a git submodule whose # .gitmodules recorded an SSH URL that a runner has no key for. + # + # fetch-depth: 0 rather than the default 1, for the workflow_dispatch path. The + # navbar version badge comes from getProjectVersion() in + # @vantagecompute/docusaurus-theme, which shells out to + # `git describe --tags --always`. + # + # A tag-triggered run is fine without this: checkout resolves refs/tags/vX.Y.Z, + # so the tag describe needs is the very ref checked out. A dispatch runs against + # a branch, and checkout fetches branches with --no-tags, so the clone has no + # tags at all and describe falls through to `--always`. Verified against a + # replica of what checkout actually runs: + # + # git fetch --no-tags --depth=1 origin
&& git describe --tags --always + # -> df7388b (a bare hash, not a version) + # + # The failure is silent: the build succeeds and the site renders, so nothing + # catches it but reading the published header. Cheap to prevent, and every other + # Vantage spoke already sets it. - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 # The API reference is generated from docstrings by the pydoc plugin, which parses # the source with `ast` and never imports it. So this needs an interpreter able to