Skip to content

Commit f57475c

Browse files
matthew-on-gitclaude
matthew-on-git
and
claude
authored
docs(container): add auto-generated tool versions page (#5)
Add /docs/container/versions/ page showing tool versions per release. A scheduled GitHub Actions workflow fetches tool-versions.json from dev-toolchain releases and regenerates the page daily. Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 8d4db71 commit f57475c

4 files changed

Lines changed: 168 additions & 0 deletions

File tree

‎.github/scripts/generate-versions-page.sh‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
#!/usr/bin/env bash
2+
# .github/scripts/generate-versions-page.sh
3+
#
4+
# Generates the Tool Versions documentation page for devrail.dev.
5+
# Fetches tool-versions.json release assets from the dev-toolchain repo
6+
# and outputs a complete Hugo markdown page to stdout.
7+
#
8+
# Usage: bash .github/scripts/generate-versions-page.sh
9+
# Requires: gh (GitHub CLI), jq, curl
10+
# Environment: GH_TOKEN must be set (provided by GitHub Actions)
11+
12+
set -euo pipefail
13+
14+
REPO="devrail-dev/dev-toolchain"
15+
16+
# --- Helpers ---
17+
18+
render_table() {
19+
local json="$1"
20+
echo "| Tool | Version |"
21+
echo "|---|---|"
22+
echo "${json}" | jq -r '.tools | to_entries | sort_by(.key) | .[] | "| \(.key) | \(.value) |"'
23+
}
24+
25+
# --- Frontmatter and intro ---
26+
27+
cat <<'FRONTMATTER'
28+
---
29+
title: "Tool Versions"
30+
linkTitle: "Tool Versions"
31+
weight: 10
32+
description: "Tool versions included in each dev-toolchain container release."
33+
---
34+
35+
<!-- This page is generated automatically by .github/workflows/update-tool-versions.yml -->
36+
<!-- Do not edit manually — changes will be overwritten on the next scheduled run. -->
37+
38+
This page shows the exact tool versions shipped in each release of the
39+
[dev-toolchain container](/docs/container/). It is updated automatically
40+
when new releases are published.
41+
42+
FRONTMATTER
43+
44+
# --- Fetch releases ---
45+
# gh api returns newest first by default. Select non-draft releases and
46+
# extract tag, date, and the tool-versions.json asset download URL.
47+
48+
releases=$(gh api "repos/${REPO}/releases" --paginate --jq '
49+
.[] | select(.draft == false) |
50+
{
51+
tag: .tag_name,
52+
date: (.published_at | split("T")[0]),
53+
asset_url: (
54+
[.assets[] | select(.name == "tool-versions.json") | .url] | first // null
55+
)
56+
}
57+
')
58+
59+
# --- Render page ---
60+
61+
first=true
62+
has_previous=false
63+
64+
while IFS= read -r release; do
65+
tag=$(echo "${release}" | jq -r '.tag')
66+
date=$(echo "${release}" | jq -r '.date')
67+
asset_url=$(echo "${release}" | jq -r '.asset_url')
68+
69+
# Skip releases without a tool-versions.json asset
70+
if [[ "${asset_url}" == "null" ]]; then
71+
continue
72+
fi
73+
74+
# Download the asset via the GitHub API (works for public and private repos)
75+
versions_json=$(gh api "${asset_url}" --jq '.' 2>/dev/null) || continue
76+
77+
if ${first}; then
78+
echo "## Latest Release: ${tag}"
79+
echo ""
80+
echo "Released ${date}."
81+
echo ""
82+
render_table "${versions_json}"
83+
echo ""
84+
first=false
85+
else
86+
if ! ${has_previous}; then
87+
echo "## Previous Releases"
88+
echo ""
89+
has_previous=true
90+
fi
91+
echo "<details>"
92+
echo "<summary><strong>${tag}</strong> (${date})</summary>"
93+
echo ""
94+
render_table "${versions_json}"
95+
echo ""
96+
echo "</details>"
97+
echo ""
98+
fi
99+
done <<< "${releases}"
100+
101+
# Fallback if no releases have the asset yet
102+
if ${first}; then
103+
echo "No releases with tool version manifests are available yet."
104+
echo "Version data will appear here after the next dev-toolchain release."
105+
fi

‎.github/workflows/update-tool-versions.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Update Tool Versions Page
2+
3+
on:
4+
schedule:
5+
# Daily at 7:00 AM UTC (1h after Monday dev-toolchain builds)
6+
- cron: '0 7 * * *'
7+
workflow_dispatch: {}
8+
9+
permissions:
10+
contents: write
11+
12+
jobs:
13+
update-versions:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Checkout repository
17+
uses: actions/checkout@v4
18+
19+
- name: Generate tool versions page
20+
env:
21+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
22+
run: |
23+
bash .github/scripts/generate-versions-page.sh \
24+
> content/docs/container/versions.md
25+
26+
- name: Check for changes
27+
id: diff
28+
run: |
29+
if git diff --quiet content/docs/container/versions.md; then
30+
echo "changed=false" >> "$GITHUB_OUTPUT"
31+
else
32+
echo "changed=true" >> "$GITHUB_OUTPUT"
33+
fi
34+
35+
- name: Commit and push
36+
if: steps.diff.outputs.changed == 'true'
37+
run: |
38+
git config user.name "github-actions[bot]"
39+
git config user.email "github-actions[bot]@users.noreply.github.com"
40+
git add content/docs/container/versions.md
41+
git commit -m "docs(container): update tool versions page"
42+
git push

‎content/docs/container/_index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,11 @@ The dev-toolchain container includes all tools needed for every supported langua
184184
| git-cliff | Changelog generation from conventional commits |
185185
| pre-commit | Git hook management |
186186

187+
## Tool Version History
188+
189+
For the exact versions of every tool in each container release, see
190+
[Tool Versions](/docs/container/versions/).
191+
187192
## Running Tools Directly
188193

189194
While the Makefile delegation pattern is the recommended approach, you can invoke the container directly for debugging or exploration:

‎content/docs/container/versions.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: "Tool Versions"
3+
linkTitle: "Tool Versions"
4+
weight: 10
5+
description: "Tool versions included in each dev-toolchain container release."
6+
---
7+
8+
<!-- This page is generated automatically by .github/workflows/update-tool-versions.yml -->
9+
<!-- Do not edit manually — changes will be overwritten on the next scheduled run. -->
10+
11+
This page shows the exact tool versions shipped in each release of the
12+
[dev-toolchain container](/docs/container/). It is updated automatically
13+
when new releases are published.
14+
15+
No releases with tool version manifests are available yet. Version data
16+
will appear here after the next dev-toolchain release.

0 commit comments

Comments
 (0)