- integrations
- Dev Containers
- Integrate
- Prebuild the container in Codespaces and CI
Prebuild the container in Codespaces and CI
This page makes a prebuilt container open with the tools from ocx.toml already fetched.
You prove it by running ocx exec with OCX_OFFLINE=1, which works only when the store is warm.
The page assumes the repository commits both ocx.toml and ocx.lock.
Know what a prebuild runs
Lifecycle commands lists every command the feature declares. The feature declares two lifecycle commands, and both run as the remote user in the workspace folder:
| Command | What it does |
|---|---|
onCreateCommand |
Applies the managed configuration when managedConfig is set |
updateContentCommand |
Runs ocx pull when pull is on, with -g <pullGroups> when that option is set |
GitHub states that a prebuild performs setup “up to and including any onCreateCommand and updateContentCommand commands” in the dev container.
See About GitHub Codespaces prebuilds.
So a prebuild runs the restore, which fetches the tools into the store in the home directory of the remote user.
The devcontainer up --prebuild command of the Dev Container CLI runs the same two commands and stops, which makes it a local stand-in.
Warm the store in a Codespaces prebuild
The defaults already do the work. pull is on, so a feature with no options restores the toolchain.
This devcontainer.json states the two relevant options for clarity:
{ "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": { "ghcr.io/ocx-sh/devcontainer-features/ocx:1": { "pull": true, "noUpdateCheck": true } }}Then enable prebuilds for the repository, as Configuring prebuilds describes.
Commit ocx.lock next to ocx.toml. Without it the restore prints exit code 78 and fetches nothing, as Error: ocx.lock not found shows.
Pull more than the default group with pullGroups, for example "pullGroups": "default,lint".
The option takes comma-separated group names, and a named list replaces the default group.
Build the container in CI
A CI job can run the same lifecycle commands with the Dev Container CLI. This workflow builds the container, runs the restore and then checks the store without a network:
name: containeron: pull_requestpermissions: contents: readjobs: check-container: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install the dev container CLI run: npm install --global @devcontainers/cli - name: Run the lifecycle commands run: devcontainer up --prebuild --workspace-folder . - name: Check the store is warm run: devcontainer exec --workspace-folder . env OCX_OFFLINE=1 ocx exec -- shfmt --versionReplace shfmt with a tool from your ocx.toml.
The actionlint tool accepts this file.
Keep prompts and update checks quiet
The options noUpdateCheck and consentPaths keep a prebuilt container free of network calls and prompts at start:
noUpdateCheckis on by default. It writesself = "manual"andtoolchain = "manual"under[update]in/etc/ocx/config.toml, soocxdoes not look for a new version.consentPathsdefaults to/workspaces/*. A project below that path activates in new shells with no prompt, and the workspace mount sits there. What the feature trusts says what that default allows.
The file in a test container reads:
[update]self = "manual"toolchain = "manual"
[shell.consent]paths = ["/workspaces/*"]Check the store is warm
After devcontainer up --prebuild in a project with a committed ocx.lock, run the tool with the network switched off for ocx:
$ devcontainer exec --workspace-folder . env OCX_OFFLINE=1 ocx exec -- shfmt --versionv3.13.1In a container with an empty store the same command exits with code 79 and package not found.
Run with no network shows that output.
A terminal in the prebuilt container finds the tools on PATH as well.
A new interactive shell in a project under consentPaths composes them from the lock when it starts.
Next steps
- Fix a lock or permission error when the prebuild log shows an
ocx-feature: warning:line. - Build behind a proxy and a custom CA when the prebuild runner sits behind a proxy.
- Restore the project toolchain on create describes the groups and the opt-out of the restore.
- Options describes
pull,pullGroupsand the other options used here.