Automatic reduced installer images¶
The installer workflow builds
the reduced AMD64 USB image. It retains Ubuntu's signed main package pool,
including the packages Subiquity needs to configure Wi-Fi, and removes only the
large restricted package archive. Additional packages come from the selected
Ubuntu mirror. The live kernel, firmware, Subiquity and installed-system
filesystem layers remain present. Network access during installation is required.
See the installer options and limitations.
These are test/prerelease downloads, not a declaration that a complete installation or GPU setup passed. The workflow does not create a versioned product release, promote container images, write a USB drive or roll out an appliance. The separate VM acceptance workflow can boot a published candidate, install it onto a blank virtual disk and verify first-run readiness. Its result is separate from the image build and from physical USB/Wi-Fi/GPU acceptance.
The project owner confirmed a successful installation of the earlier online-only candidate on 24 September 2026. The dated installation result records that confirmation separately from the original CI evidence. The later network-screen finding showed that candidate could not bootstrap Wi-Fi support. The reduced installer is now the standard USB path; physical Wi-Fi acceptance of each new candidate remains separate from CI. Successful manual tests do not rewrite published build manifests or imply compatibility with every GPU.
For installation, use the prebuilt image in the USB guide. The v1.0.0 delivery record separates its public download verification from physical installation acceptance. The build scripts are developer tools. Users do not need to clone this repository or install Docker to prepare the standard USB installer.
Local development builds¶
Use a local build only when changing or testing the installer, comparing media modes or preparing a custom deployment. Install Git and Docker or Podman, clone the repository, and run from its root:
magic-installer/build-installer-image.sh \
--hostname example-host-01 --offline-pool reduced \
--output dist/magicstick-installer-reduced.img
On Windows, the equivalent developer wrapper is:
.\magic-installer\build-installer-image.ps1 `
-Hostname example-host-01 -OfflinePool reduced `
-Output dist\magicstick-installer-reduced.img
Choose a new output filename for each rebuild. The wrappers preserve existing
images. reduced is the default and matches the standard published media;
full remains an explicit compatibility option. Private/custom images must not be
uploaded as public downloads. For advanced metadata, optional command-line USB
writers and the media layout, see the developer tool reference.
Build once for each installer recipe¶
A push to main starts the workflow only when an installer input or its focused
tests change. Old develop downloads remain historical. A manual main run may set
product_version to an already verified product tag, generating fixed-version
media rather than a main follower. The product-release completion step dispatches
on the exact matching product tag automatically. Both planning stages require
that tag's expected commit and retain the same product identity. A mismatched or
empty version on a tag dispatch stops before planning. Local wrappers default to stable resolution.
Before building, the workflow computes a SHA-256 fingerprint from:
- the build scripts, media helper, Containerfile, optional Docker ignore file,
user-dataandmeta-datatemplates; - the pinned Ubuntu ISO URL and checksum;
- the workflow, artifact helper and public CI build configuration;
- the source license terms (
LICENSEandLICENSING.md); - the explicit development channel or verified product-release identity.
For development main candidates, the source commit/product version are not cache keys. For fixed media the exact version, approved commit, tag object, published manifest digest and original license record are fingerprint inputs. Changing the version/identity cannot reuse an older branch-following image. Dashboard, model, host-automation, documentation, changelog or release-date changes alone do not rebuild a development installer. Its first boot fetches the selected branch's current source, rather than embedding all components. Fixed media instead verify and check out their embedded product tag/commit; they never follow newer tags.
If a complete, matching download already exists, CI verifies its manifest, checksums, sizes and original source tag, then reports the existing download URL. It does not rebuild or upload a duplicate. A manual run follows the same rule. A changed input produces a new fingerprint and a separate download.
The fingerprint describes the recipe, not byte-for-byte reproducibility:
image timestamps and build-tool packages may differ between builds. For an
intentional toolchain refresh without another recipe change, increment
recipeRevision in ci-build.json.
Update the pinned ISO URL/checksum to adopt a new Ubuntu installation baseline.
The source-ISO cache is only a download optimization; its contents are always
checksum-verified, and eviction cannot make CI lose a published image.
Downloads and channels¶
New candidates are stored as GitHub prerelease assets under
installer-<channel-or-product-version>-<full-input-fingerprint>. They are not marked as the latest
product release. The workflow summary links to the download containing:
| Asset | Purpose |
|---|---|
*.img |
Bootable USB image |
*.img.sha256 |
Image checksum, usable with sha256sum -c or shasum -a 256 -c |
*.build.json |
Original source commit/run, input fingerprints and asset checksums |
*.evidence.tar.gz |
Media checks, package inventories and source license notices |
GitHub's generated source archives are not installer images. Each attached file must stay below GitHub's 2 GiB release-asset limit. The pipeline rejects larger files rather than silently splitting them.
Published assets do not use Actions' temporary artifact retention. The 14-day Actions artifact is only the handoff between build and publication jobs. Original tags, image bytes, source revision and notices are preserved when reused. Product release notes can link an existing installer without rebuilding or relabeling it. The user-facing USB guide pins verified v1.0.0 media. After publishing a new baseline, verify its download and checksums, then deliberately update that guide's image/checksum/evidence links together. Documentation-only changes do not rebuild the image. Do not use GitHub's generic “latest release” URL: product and installer releases have different lifecycles, and installer candidates are prereleases.
Product release delivery is complete only after the exact installer workflow and
current build/publication jobs are successful, all four public asset URLs and
bytes are verified, and the product page's download links are read back. The
image is streamed in bounded chunks and checked against its published SHA-256;
API asset metadata or an Actions artifact alone is not public delivery. Explicit
workflow_dispatch works even when product creation used GITHUB_TOKEN; no
new publisher credential or recursive release-event trigger is needed.
The product tag may be visible earlier. A failed/active newer attempt blocks
completion, rather than inheriting old green media or starting an automatic rerun.
Explicit development main media follows main; historical develop media follows
develop. Product-version media embeds its tag/approved SHA and verifies them again
at first boot. Public CI fixes the
hostname to example-host-01, uses public example domains and readonly-public,
and embeds no GitHub token, user password or SSH access. Inspect/edit CIDATA for
the target computer as described in the installer guide.
CI does not offer private-bootstrap inputs.
Verification and recovery¶
The build job has read-only repository access. It checks the focused installer tests, source-license consistency, advisory license review and public source secret scan before building. Open approval records remain visible; the review does not invent legal clearance or block publication solely on missing approvals. Afterward it verifies image checksums, removal of the restricted package pool, retention of the signed main package pool, protected kernel/firmware/installer files, BIOS/UEFI boot entries and the actual public CIDATA configuration. It packages reports and original source notices. These integrity checks are not a boot test or a completed installation.
A separate publication job can write releases, but does not build media. It
restores the plan with the same explicit product_version input as the build,
including the verified product tag, commit, manifest and original license record;
omitting that input must not turn fixed media into a development-channel plan.
An owning test executes both workflow planning shell steps and compares their
actual artifact fingerprints for fixed-version and development media. It
verifies the exact successful build run, downloaded asset bytes and remote
upload checksums. It uploads to a draft first and publishes the prerelease only
after all four assets match. There is no overwrite or mutable latest.img alias.
Normal source/license checks do not claim legal or physical acceptance.
- A GitHub authentication, network or rate-limit failure stops the lookup; it must not cause a duplicate build.
- An incomplete draft or existing tag without a complete release stops a fresh run. Rerun only the original failed publication job while its 14-day Actions artifact is available. Rebuilding would produce different image bytes.
- If original artifacts have expired, recover the original bytes and evidence through a reviewed maintenance procedure, or deliberately bump the recipe revision to create a new candidate. Do not move the old tag or overwrite assets.
- After changing workflow or helper inputs, run
python tools/license_audit.py --refresh-referencesif the dependency-reference check reports stale evidence; this refresh does not approve distribution reviews.
After publishing the workflow source, the first relevant push or an authorized manual run builds/publishes a candidate. Repository rules must permit Actions to create the installer tags and releases. Local tests alone do not prove that a GitHub-hosted run or publication has succeeded. Keep the installation/first-boot and GPU checks from the release checklist separate.