Skip to content

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: container
on: pull_request
permissions:
contents: read
jobs:
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 --version

Replace 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:

  • noUpdateCheck is on by default. It writes self = "manual" and toolchain = "manual" under [update] in /etc/ocx/config.toml, so ocx does not look for a new version.
  • consentPaths defaults 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:

Terminal window
[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:

Terminal window
$ devcontainer exec --workspace-folder . env OCX_OFFLINE=1 ocx exec -- shfmt --version
v3.13.1

In 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