Prebuild a Workspace

A prebuild is an image built ahead of time from devcontainer.json, its features, and any Dockerfile. When a matching prebuild exists, Devsy uses it instead of building.

How it worksCopy Anchor Link

Devsy computes a prebuild hash from the target architecture, the build-relevant parts of devcontainer.json (name, features, image, Dockerfile and build settings), the Dockerfile contents, and the build context, excluding files matched by .dockerignore. The image tag is devsy- followed by 32 hex characters. Devsy looks for that tag in each prebuild repository and uses the image if found.

Build and push a prebuild:

devsy workspace build github.com/my-org/my-repo --repository ghcr.io/my-org/my-repo

If the repository already has the matching tag, the build is skipped and nothing is pushed. Otherwise Devsy builds and pushes the image. Pushing requires write access to the repository; if the push permission check fails, the build fails with cannot push to repository.

Use a prebuildCopy Anchor Link

Pass the repository when you create a workspace:

devsy workspace up github.com/my-org/my-repo --prebuild-repo ghcr.io/my-org/my-repo

Or set it in devcontainer.json. The value can be a string or an array. Devsy checks every entry when looking for a prebuild, and pushes to the first entry:

{
  "name": "my-project",
  "customizations": {
    "devsy": {
      "prebuildRepository": "ghcr.io/my-org/my-repo"
    }
  }
}

If a repository lookup fails, including because of missing credentials, Devsy continues with the next repository. If no matching image is found, it falls back to building as usual. If Devsy finds an image but cannot inspect it, the build fails.