chore: Use devcontainers

[PierreQuinton]

No description provided.

[ValerianRey]

Quite cool! Let's make it work and then I'll do a more in-depth review

[ValerianRey]

That's not really how it works. Cuda comes with torch so you don't necessarily even have a cuda version. The correct wording would be: with the latest cuda version you GPU is compatible with.

[ValerianRey]

Could these come with the container?

[PierreQuinton]

Yes, the downside is that the container will weight 2-4GB more and this becomes "mandatory" for all contributors. Concerning caching dockers with Github, no problems.

[PierreQuinton]

/opencode:Plan Can you try to explain why this is still very slow? the Build Devcontainer action took 8 minutes and is blocking for the rest. So caching seems to not be effective. Can you suggest improvement ideas?

[opencode-agent]

Here is my analysis of why the "Build devcontainer" job is slow and several concrete improvements.

Why it's slow (and caching is ineffective)

1. The registry cache is likely cold. The separate build-devcontainer.yml only runs on main to populate the :cache tag. Since this PR hasn't been merged yet, no :cache manifest exists on GHCR for checks.yml to pull from.
2. pyproject.toml invalidates the expensive layer. The Dockerfile copies pyproject.toml before running uv pip install. In a PR, even a tiny change to pyproject.toml busts Docker's layer cache for the entire dependency installation. uv is fast, but reinstalling torch and all extras from scratch inside a container still takes minutes.
3. You are pushing a multi-GB image on every PR. checks.yml does push: true and tags the image with ${{ github.sha }}. Downstream jobs need the image, so it must be pushed to GHCR, but uploading a 2–4 GB image is inherently slow.
4. Fork PRs will make this worse. On PRs from forks, GitHub downgrades the GITHUB_TOKEN to read-only for packages. Even with permissions: packages: write, fork PRs cannot push the :cache tag, so the cache will never be updated.

Suggested improvements

1. Add a uv cache mount to the Dockerfile (biggest win)

Even if the Docker layer is invalidated, uv can reuse its downloaded package cache. This turns a 5+ minute uv pip install into a 10–30 second one.

In .devcontainer/Dockerfile, change:

RUN uv venv /opt/venv \
    && uv pip install --python-version=3.14 -e '.[full]' --group check --group doc --group test --group plot

To:

RUN --mount=type=cache,target=/root/.cache/uv \
    uv venv /opt/venv \
    && uv pip install --python-version=3.14 -e '.[full]' --group check --group doc --group test --group plot

(BuildKit, used by docker/build-push-action, supports --mount=type=cache by default.)

2. Cache from both :cache and :latest

If the dedicated :cache manifest is missing, you can still reuse layers from the :latest image.

In both workflow files, change cache-from to:

cache-from: |
  type=registry,ref=${{ steps.image.outputs.cache-ref }}
  type=registry,ref=ghcr.io/${{ github.repository_owner }}/devcontainer:latest

3. Use GitHub Actions cache (type=gha) instead of registry cache for PRs

Registry cache requires push/pull and write permissions. GHA cache works for fork PRs and doesn't pollute GHCR with per-PR images.

In checks.yml, switch to:

cache-from: type=gha
cache-to: type=gha,mode=max

And set push: false to avoid the upload overhead. However, this creates a new problem: downstream jobs run on fresh VMs and won't see the locally-built image.

4. Decouple CI checks from the devcontainer build (most pragmatic)

The tests job already installs dependencies natively with setup-uv in ~30 seconds because uv has excellent built-in caching via GitHub Actions. Building a Docker image just to run pre-commit and sphinx adds 8 minutes of overhead for no real benefit in CI.

My recommendation:

• Keep the devcontainer for local development consistency.
• In checks.yml, make build-doc and code-quality run directly on ubuntu-latest using setup-uv (just like the tests job), installing the project with the appropriate dependency groups.
• Keep build-devcontainer.yml solely as a periodic smoke-test that the devcontainer still builds.

This avoids the 8-minute block entirely, eliminates the need for packages: write in PR checks, and makes fork PRs work flawlessly.

5. If you must keep the current architecture, make the build conditional

Only build the devcontainer in checks.yml if .devcontainer/Dockerfile or pyproject.toml actually changed. Otherwise, pull the existing ghcr.io/.../devcontainer:latest image. You can use dorny/paths-filter or a custom git diff step to detect changes and skip the build.

opencode session  |  github run

[PierreQuinton]

/opencode:Build Can you implement the change you mentioned?

[opencode-agent]

Done! I've implemented the performance improvements from my previous analysis:

1. Added uv cache mount to the Dockerfile (.devcontainer/Dockerfile)

The RUN command now includes --mount=type=cache,target=/root/.cache/uv. This is the biggest win: even when pyproject.toml changes and invalidates the Docker layer, uv can reuse its downloaded package cache. This turns a 5+ minute reinstall into a 10–30 second operation.

2. Added :latest fallback to cache-from in both workflows

• .github/workflows/checks.yml: cache-from now tries both :cache and :latest
• .github/workflows/build-devcontainer.yml: Same dual cache-from strategy, and I also removed the logic that disabled cache reads entirely on PRs. PR builds can now still pull cache layers from GHCR; only cache writes are skipped on PRs (which avoids permission issues with forks).

These changes are minimal and safe — they don't change the CI architecture, but they should significantly reduce the devcontainer build time, especially on PRs that touch pyproject.toml.

opencode session  |  github run

[PierreQuinton]

/opencode:Build Can you also do 3 and 4?

[opencode-agent]

Done! I've implemented suggestions 3 and 4 from the analysis.

Changes made

1. checks.yml — Decoupled CI checks from the devcontainer build (Suggestion 4)

• Removed the build-devcontainer job entirely from checks.yml. It was blocking all downstream jobs for 8+ minutes on every PR.
• build-doc and code-quality now run natively on ubuntu-latest using astral-sh/setup-uv@v7 and the existing ./.github/actions/install-deps composite action — exactly like the tests job.
  • build-doc installs with options: full, groups: doc and runs uv run make dirhtml / uv run make doctest.
  • code-quality installs with options: full, groups: check test plot and runs uv run pre-commit / uv run ty.
• These jobs now run in parallel with tests instead of waiting for a multi-GB image build + push, eliminating the 8-minute bottleneck.

2. build-devcontainer.yml — Use GHA cache for PR builds (Suggestion 3)

• PR builds now use type=gha for both cache-from and cache-to (mode=max). This avoids any dependency on GHCR push/pull permissions during PRs, which makes fork PRs work reliably and prevents polluting the registry with temporary images.
• main branch builds keep the registry-based cache strategy (:cache and :latest fallback) and still push the final :latest image to GHCR.
• Simplified the workflow by splitting the single build step into two conditional steps (PR vs main) for clarity.

Result

• checks.yml no longer needs packages: write permissions.
• Fork PRs will no longer be blocked by devcontainer build failures or permission issues.
• The overall CI wall-clock time for PR checks should drop by ~8 minutes.

opencode session  |  github run