CONTRIBUTING#
Thanks for helping out!
dakota-iso builds the bootable live ISO for Dakota, including the live environment and installer wiring. Changes here affect the bootable installer path ā test locally before pushing.
Before you start#
Read AGENTS.md and the relevant skill file in docs/ before making changes.
The docs are the source of truth for build quirks, disk space requirements, and CI constraints.
Prerequisites#
podman(rootless)xorriso(via brew:brew install xorriso, or distro package)mtools(via brew or distro)cosignandjqājust container/just isoverify the cosign signature of the live base image before building (a pinned cosign is fetched automatically if missing)- ~25 GB free disk space on
/var(not/tmpā tmpfs is too small) - See
docs/build.mdfor full setup details
Local build workflow#
git clone https://github.com/projectbluefin/dakota-iso
cd dakota-iso
just iso-sd-boot dakota # full ISO build
just iso-sd-boot dakota-nvidia # nvidia variant
just boot-iso-serial dakota # boot + smoke test in QEMU
PR workflow#
All PRs target main. PRs require:
- A description of what changed and why
- Evidence that the ISO built and booted (or explicit statement it's a docs/ci-only change)
- Both AI attribution trailers if AI-assisted (see
AGENTS.md)
gh pr create --repo projectbluefin/dakota-iso --base main
CI#
Two workflows run on PRs:
lint.ymlā shell and YAML hygienetest.ymlā container build smoke test
Full ISO builds and LUKS E2E tests run on push to main and weekly. See docs/ci.md.
Related repos#
projectbluefin/dakotaā source images this repo packages into ISOsprojectbluefin/commonā shared OCI layer, org-level factory docstuna-os/bootc-installerā the Flatpak installer bundled in the live ISO
Useful validation steps:
just container dakota
just boot-iso-serial dakota
just boot-iso-serial <target> is the quickest local smoke test for a bootable ISO.
Repo notes#
- Key scripts:
live/src/build-iso.shandlive/src/configure-live.sh - The
justfileis the canonical interface for local work - Prefer small, surgical changes: this repo feeds the Dakota installer media
Pull requests#
- Open PRs against
main - Use Conventional Commits (
docs:,fix:,feat:, etc.) - In the PR description, say what you built locally and how you verified boot/install behavior
- If you touch build logic or installer behavior, test the resulting ISO before pushing
Use the shared label workflow
and Prow commands: humans triage with /triage accepted, review with /lgtm,
and approve with /approve. Never write to ublue-os/*.