Skip to content

Implement OCI image support #416

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jserv merged 4 commits into from
Oct 11, 2026
Merged

Implement OCI image support #416

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6c200f0
Remove the Go OCI image tool
henrybear327 Oct 6, 2026
cf1d55d
Add elfuse-oci based on crane and umoci
henrybear327 Oct 6, 2026
d069de7
Run the OCI front end in CI
henrybear327 Oct 6, 2026
c3c52b4
Document the OCI front end
henrybear327 Oct 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 52 additions & 21 deletions .github/workflows/build.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
# build-macos : compile + entitlement check on macOS Apple Silicon
# runtime-macos : HVF runtime tests on self-hosted Apple Silicon,
# including release, ASAN, UBSAN, and TSAN variants
# oci-smoke : OCI front end lane on self-hosted Apple Silicon
#
# Runtime and sanitizer tests require Hypervisor.framework, which
# GitHub-hosted macOS runners do not expose. Those tests run on self-hosted
Expand Down Expand Up @@ -126,27 +127,6 @@ jobs:
retention-days: 7
if-no-files-found: warn

oci-linux:
name: elfuse-oci (Linux)
runs-on: ubuntu-24.04
timeout-minutes: 20
steps:
- name: Checkout
uses: actions/checkout@v7

- name: Set up Go
uses: actions/setup-go@v7
with:
go-version-file: go.mod

- name: Build, lint and test elfuse-oci
run: |
set -euo pipefail
go version
make elfuse-oci
make oci-lint
make oci-test

runtime-macos:
name: Runtime (${{ matrix.name }})
needs: build-macos
Expand Down Expand Up @@ -429,3 +409,54 @@ jobs:
else
echo "No externals/test-fixtures to save"
fi

oci-smoke:
name: OCI smoke
needs: build-macos
if: >
github.repository == 'sysprog21/elfuse' &&
(github.event_name == 'push' || github.event_name == 'pull_request' ||
github.event_name == 'workflow_dispatch' ||
github.event_name == 'merge_group')
runs-on: [self-hosted, macOS, arm64]

@cubic-dev-ai cubic-dev-ai Bot Oct 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: This new self-hosted runner job omits the "Fail fast if superseded by a newer PR commit" guard that runtime-macos has for exactly the same [self-hosted, macOS, arm64] runner. Its step comment documents the cost: a manual "Re-run jobs" replays the frozen head.sha and burns the full job timeout re-testing stale code on the shared runner. oci-smoke inherits that 30-minute waste. Add the same guard step (pull the PR's live HEAD, compare with pull_request.head.sha, exit 1 on mismatch).

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At .github/workflows/build.yml, line 421:

<comment>This new self-hosted runner job omits the "Fail fast if superseded by a newer PR commit" guard that `runtime-macos` has for exactly the same `[self-hosted, macOS, arm64]` runner. Its step comment documents the cost: a manual "Re-run jobs" replays the frozen `head.sha` and burns the full job timeout re-testing stale code on the shared runner. `oci-smoke` inherits that 30-minute waste. Add the same guard step (pull the PR's live HEAD, compare with `pull_request.head.sha`, exit 1 on mismatch).</comment>

<file context>
@@ -429,3 +409,30 @@ jobs:
+      (github.event_name == 'push' || github.event_name == 'pull_request' ||
+      github.event_name == 'workflow_dispatch' ||
+      github.event_name == 'merge_group')
+    runs-on: [self-hosted, macOS, arm64]
+    timeout-minutes: 30
+    steps:
</file context>

timeout-minutes: 30
steps:
- name: Checkout
uses: actions/checkout@v7

- name: Download prebuilt elfuse binary
uses: actions/download-artifact@v7
with:
name: elfuse-${{ runner.os }}-${{ runner.arch }}
path: build

- name: Set up Go
uses: actions/setup-go@v7
with:
go-version: '1.27'
cache: false

- name: Build crane and umoci
# go install refuses umoci: its go.mod has a replace directive.
env:
CRANE_VERSION: v0.22.1
UMOCI_VERSION: v0.6.0
run: |
set -euo pipefail
bin="$RUNNER_TEMP/oci-tools"
GOBIN="$bin" go install \
"github.com/google/go-containerregistry/cmd/crane@$CRANE_VERSION"
umoci="github.com/opencontainers/umoci@$UMOCI_VERSION"
go mod download "$umoci"
go build -C "$(go env GOMODCACHE)/$umoci" -o "$bin/umoci" ./cmd/umoci
echo "$bin" >> "$GITHUB_PATH"
"$bin/crane" version
"$bin/umoci" --version

- name: Run the OCI smoke lane
# A downloaded artifact keeps its signature but not its execute bit.
# Runners on one host share $HOME, so each gets its own store.
run: |
set -euo pipefail
chmod +x build/elfuse
ELFUSE_OCI_STORE="$HOME/.cache/elfuse-ci/oci-smoke-$RUNNER_NAME" scripts/ci/oci-smoke.sh
1 change: 0 additions & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -793,4 +793,3 @@ include mk/lint.mk
include mk/verify.mk
include mk/format.mk
include mk/help.mk
include mk/oci.mk
9 changes: 5 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,9 @@ linker resolved against an external sysroot via `--sysroot`.

## OCI Images

`elfuse-oci` is a separate Go binary that pulls OCI images into a local
OCI image layout. It does not add container isolation. See
`scripts/elfuse-oci.py` pulls OCI images with crane, unpacks each once with
umoci into a read-only case-sensitive volume, and runs it under elfuse with a
per-run writable shadow. It does not add container isolation. See
[docs/usage.md](docs/usage.md#oci-images) and
[docs/oci-images.md](docs/oci-images.md).

Expand Down Expand Up @@ -158,8 +159,8 @@ The build signs `build/elfuse` before use. Override the signing identity with
- [docs/testing.md](docs/testing.md): build prerequisites, the
`make check` flow, the QEMU and Rosetta cross-check matrices, and
fixture handling.
- [docs/oci-images.md](docs/oci-images.md): the `elfuse-oci` store,
pull behavior, and validation.
- [docs/oci-images.md](docs/oci-images.md): the OCI image store, sealed
volumes, per-run shadows, and validation.
- [docs/filenames.md](docs/filenames.md): how a guest filename becomes a
name on disk and back: case folding and normalization on the sysroot
volume, the escape encoding, and the length limits both systems impose.
Expand Down
96 changes: 0 additions & 96 deletions cmd/oci/common.go
View file
Open in desktop

This file was deleted.

60 changes: 0 additions & 60 deletions cmd/oci/common_test.go
View file
Open in desktop

This file was deleted.

61 changes: 0 additions & 61 deletions cmd/oci/flock.go
View file
Open in desktop

This file was deleted.

Loading
Loading