Migrate GeoServer documentation builds from Jenkins to GitHub Actions following the approved GSIP 221 (MkDocs Migration). Jenkins could continue building after RST removal with additional reconfiguration work, but GitHub Actions provides superior maintainability through version-controlled configuration and eliminates SSH credential management.
Key Benefits:
Version-controlled configuration: YAML in Git (reviewable, auditable) vs Jenkins UI (manual)
No credential management: GitHub tokens (automatic) vs SSH keys (manual rotation)
Faster deployment: Immediate trigger (<10s) vs polling (0-5 min delay)
Better maintenance: Git-tracked changes vs manual Jenkins UI edits
As written it buries the lede somewhat - the change in hosting from OSGeo to GitHub Pages is in my opinion just as important (if not more so) as the change in build system, but isn’t explicitly described until partway through the “Build Infrastructure” section.
Along similar lines, one downside in changing to GitHub Pages is that we will no longer have ownership (“we” being OSGeo as a whole) over the build or hosting infrastructure. While I think the ease-of-maintenance gained here is worth the loss of ownership, it would still be worth calling out as a downside in the proposal.
I do think these tradeoffs are still worth it for a faster and easier docbuild, so I’m still giving my +1 to this proposal, but it would be nice if they were called out more clearly.
Thank you for the insights @tbarsballe . They are much appreciated.
Loss of ownership - is this important to the project (historically, before I got involved)? If so, then I think it’s definitely worth spending the time to update the build Docs job in Jenkins - I can tackle this next. The downside is the lack of version-controlled configuration, but perhaps these Jenkins jobs can be added as a folder in the GeoServer · GitHub repo (but they’re likely to get out of sync).
Is the proposed change in hosting from OSGeo to GitHub pages seen as positive or negative? Do we have a CDN in front of OSGeo?
Thank you for your support, but I would like your input on what is important to the project.
Makes sense, but I know we’ll have to maintain the documentation for the 2.x series for a while, just because many will be shy to update (I don’t expect the 2.x series to really end in march 2027, but we’ll see). So it means we’ll have to perform manual backports of anything that involves documentation, and rewrite from MD to rst, for at least 1 year, possibly more.
Hence, my lack on “enthusiams” in the vote.
