Including the built HTML in repo

[achow101]

One of the issues we have had with the website build server is that it occasionally fails to build the site, and resolving those issues is actually quite annoying. One suggestion that @TheBlueMatt has is that we should be committing the built HTML into the repo, and deployment for the website can be reduced to running verify-commits.py and then copying the HTML.

This does give us several advantages:

• since we won't be limited by what dependencies can be installed on the build machine, we can use whatever build dependencies we want
• reduces the attack surface on the website infrastructure
• makes maintaining the website infrastructure easier

The main drawback with this process would be requiring all contributors to commit the built HTML in their PRs. Given that we do get contributors who are not necessarily developers so may not have the build environment setup, this could be an additional burden that reduces contributions of things like translations. This could be mitigated by having a CI task or bot which does the build and opens a PR containing the HTML after something is merged. It may be possible to also configure the maintainer merge script to perform and commit the build during the merge, but I'm not sure if that is desirable.

Any opinions?

[ryanofsky]

The main drawback with this process would be requiring all contributors to commit the built HTML in their PRs.

Would another drawback be that this would require people to manually review the generated code?

[katesalazar]

nah, rules could be: - trusted contributor can optionally give object docs - non trusted contributor is disallowed to give object docs

…

On Wed, Aug 13, 2025 at 1:23 PM Ryan Ofsky ***@***.***> wrote: *ryanofsky* left a comment (bitcoin-core/bitcoincore.org#1162) <#1162 (comment)> The main drawback with this process would be requiring all contributors to commit the built HTML in their PRs. Would another drawback be that this would require people to manually review the generated code? — Reply to this email directly, view it on GitHub <#1162 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AMRS4W4XPAKCZ3GMUB7CG7D3NM343AVCNFSM6AAAAACDXHOYZGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTCOBTHEYDSNZYG4> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[achow101]

Would another drawback be that this would require people to manually review the generated code?

I don't think so. It should be possible to reproducibly build the site so review can be building the site and checking the diff matches. We should be able to do that as part of CI.

[ryanofsky]

Yeah if there is CI that seems reasonable. I'm not sure why getting a CI job that generates the site to work reliably would be easier than getting the "website build server" to work reliably, but I could imagine that being the case. And I guess if CI fails you have flexibility to override it and check in manual output.

[achow101]

I'm not sure why getting a CI job that generates the site to work reliably would be easier than getting the "website build server" to work reliably, but I could imagine that being the case.

The build server needs to run in close proximity to the actual web server. Because of that, it has heightened security requirements which limits where we can install dependencies from, and what those are. The result is really that we can't/don't use bundler and ruby gems to install the dependencies which makes building the site much more annoying.

In contrast, CI can use bundler and ruby gems to do the build since the hardware is neither ours nor has those security requirements.

[achow101]

Another downside is that all PRs will have a merge conflict with each other on the html, so I think having everyone include the HTML might not be viable.

[TheBlueMatt]

That seems like an argument for having a CI task that opens a "update HTML" PR after PRs get landed rather than doing it in the PR editing the content itself.