How to publish Web exports to GitHub Pages or GitLab Pages

[umarcor]

In didactic and open source use cases, either GitHub or GitLab are great candidates to learn not only about game/app development, but also about code management, collaboration, continuous integration and continuous delivery. They provide a self-contained and integrated platform usable with the same credentials, which help contain the complexity for less experienced users.

As shown in itsas-taldea/moon@c3af5fe, a 100L workflow allows pushing nightly builds of a game/app as assets of a pre-release and pushing the Web export to GitHub Pages. Actually, itsas-taldea/moon@c3af5fe#diff-6a2171377b76ef901cd435c887d2fa50ebd9d736cc3002a326e43d84247ee0e6R50-R56 would be reduced to the last two lines if official Godot containers were available (see godotengine/godot-commit-artifacts#1).

Very unfortunately, that works nicely with Godot 3.x but not with Godot 4.x. Since Godot 4.0, a priori, Web exports cannot be hosted on GitHub Pages or GitLab Pages because SharedArrayBuffer is a required feature and since 2018 it is disabled by default in many environments due to Spectre. Since 2020, a new secure approach was standardised, which requires Cross Origin Isolation. That's unfortunately not enabled on GitHub Pages or GitLab Pages by default. The following error is shown:

Error
The following features required to run Godot projects on the Web are missing:
Cross Origin Isolation - Check web server configuration (send correct headers)
SharedArrayBuffer - Check web server configuration (send correct headers)

Other free hosting solutions, such as Itch.io, have an explicit option to enable SharedArrayBuffer and thus make it easier to publish Godot games on the web. However, those hosting solutions don't typically have a platform for software development (SCM, issues, PRs, etc.) or to host the docs along with the game/app.

Fortunately, there is a workaround: gzuidhof/coi-serviceworker. Adding coi-serviceworker.js to the Web export and including <script src="coi-serviceworker.js"></script> in the index.html allows Godot 4.0 Web exports to be hosted on GitHub Pages or GitLab pages without the SharedArrayBuffer error!

Therefore, I wonder if this should be documented in https://docs.godotengine.org/en/latest/tutorials/export/exporting_for_web.html.

Furthermore, I wonder if such functionality can be built into Godot's Web export as an option. As reported in #6970, in the current stable documentation SharedArrayBuffer is described as an optional dependency (see https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_web.html#exporting-for-the-web and https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_web.html#export-options). However, in the latest, SharedArrayBuffer was elevated to a requirement and apparently export option Threads was made the regular/default and only type (see https://docs.godotengine.org/en/latest/tutorials/export/exporting_for_web.html#exporting-for-the-web and https://docs.godotengine.org/en/latest/tutorials/export/exporting_for_web.html#export-options). I guess that making SharedArrayBuffer a requirement was a last moment decision and there was some latency until the docs were updated. Hence, assuming that the non-threaded option is never expected to come back, I believe it would be sensible to try handling the lack of headers silently, rather than requiring users to customise the exports.

[umarcor]

FTR: https://github.com/itsas-taldea/moon/blob/e4c1d959e6e54ef94c1152e9b9daab62ba3611a1/.github/workflows/Pipeline.yml#L107-L112

      # Workaround for SharedArrayBuffer support on GitHub Pages
      # See: https://github.com/godotengine/godot-docs/issues/7084
      - run: |
          cd public/play
          curl -fsSL https://github.com/gzuidhof/coi-serviceworker/raw/master/coi-serviceworker.js > coi-serviceworker.js
          sed -i 's#\(		<script src="index.js"></script>\)#		<script src="coi-serviceworker.js"></script>\n\1#g' index.html

[umarcor]

Juan Linietsky, Godot as an Open Ecosystem, GDC 2023, https://youtu.be/XduuHNOGGqI?t=194

HTML5 export is still a pain because we made Godot 4 heavily multi-threaded, but browsers don't like that. So, we probably need to make a version into Godot 4.1 that is not multi-threaded, like in Godot 3, for it to work properly on the browsers.

[clayjohn]

I agree this should be mentioned in the docs until the need for sharedArrayBuffer is removed in the engine.

As for adding coi-serviceworker to the engine, there is an open proposal to do that as well godotengine/godot-proposals#6616