Prebuilts: How to keep the prebuilt image and the git repository in sync?

[imphil]

I have a repository with a devcontainer.json, which is based off a generic image and installs various tools we need into the container. It takes around 20 minutes to build the container, so I'm exploring prebuilt Dev Containers.

It is my understanding that the basic idea is to

1. Have .devcontainer/devcontainer.json referencing the prebuilt image in "image": "registry.io/my-prebuilt"
2. Have a different devcontainer.json somewhere (I've seen .github/.devcontainer/devcontainer.json) with the real devcontainer.json that builds the whole Dev Container from scratch (i.e., the thing we currently have in .devcontainer/devcontainer.json without prebuilds)
3. Have some CI in repo:main that creates the prebuild and pushes it it to the registry.

That's all nice, but begs the question: what image version do I specify in "image": "registry.io/my-prebuilt" to ensure that users always get a prebuild that matches the version (SHA) of the git repository they have checked out? I'd expect something like "image": "registry.io/my-prebuilt:git-repo-sha", where git-repo-sha is automatically appended to match the version of the repository when users open the Dev Container.

The only documentation/examples I found were always using latest, which works fine as long as users check out the current main branch.

What approach are others taking here? And what is GitHub Codespaces doing? Some extra magic sauce on top?