Build a live roadmap website from GitHub release milestones across several repositories.
The generated site is a single static page. It reads milestones, issues and pull requests from the public GitHub API in the visitor's browser, so the roadmap is always current without rebuilding the site. It is used for the mllam community roadmap.
Milestone names decide where an item appears:
vX.Y.Z: the item is on the roadmap for that release.vX.Y.Z (proposed): the item is proposed for that release.
For each release the page shows three lanes: open issues/PRs on the roadmap,
open proposed issues/PRs, and pull requests already merged into the vX.Y.Z
milestone. Open pull requests also show their review status. Milestones with
other names are ignored.
Write a roadmap.toml describing your roadmap (see
examples/roadmap.toml for every option):
title = "My Community Roadmap"
subtitle = "Upcoming work across our packages"
source_url = "https://github.com/my-org"
[home]
text = "My Community"
url = "/"
# One [[repos]] entry per repository; add as many as you like, in display order.
[[repos]]
owner = "my-org"
name = "my-package"
description = "What this package does."Then build the site:
uvx github-milestone-roadmap build --config roadmap.toml --output _site/roadmapThis writes index.html, app.js, styles.css and config.json to the
output directory. The page only uses relative paths, so it can be served from
any subpath.
Pin the version so that roadmap tool updates reach your site only when you bump it:
- uses: astral-sh/setup-uv@v6
- name: Build roadmap
run: uvx github-milestone-roadmap==0.1.0 build --config roadmap.toml --output _site/roadmap
- uses: actions/upload-pages-artifact@v3
with:
path: _siteSee the mllam.github.io deploy workflow for a complete example.
Without authentication, the GitHub API allows 60 requests per hour per
visitor. The page makes three requests per repository (open milestones, open
issues/PRs, recently closed PRs) plus one per displayed open pull request for
its review status. Responses are cached in the browser's localStorage for 15
minutes under the config's cache_key, and stale cached data is shown if the
rate limit is reached.
changes prints the issues and pull requests added to a vX.Y.Z milestone in
the last 24 hours across the configured repositories, grouped per repository
and version. The output is Markdown with nested lists, suitable for pasting
into Slack.
It uses the GraphQL API, so a GitHub token is required. With the
gh CLI logged in:
uvx github-milestone-roadmap changes --config roadmap.toml --token "$(gh auth token)"or set GITHUB_TOKEN in the environment. Use --hours N to change the
look-back window.
uv run pytest
uv run pre-commit install # ruff lint and format on commitTo preview the page locally:
uv run github-milestone-roadmap build --config examples/roadmap.toml --output _site
python3 -m http.server --directory _site 8080Then visit http://localhost:8080. The page needs config.json from the build,
so opening index.html directly from disk will not work.
Versions come from git tags (hatch-vcs). To release, update CHANGELOG.md,
merge to main, then tag vX.Y.Z on main and push the tag. The release
workflow publishes to PyPI with trusted publishing.