Skip to main content
Version: master

Container Builds

Product containers (pv-avahi, pv-tailscale, pv-mqtt-sdk, ...) are built and published separately from the BSP images. The list lives in .github/containers.json; every workflow builds all containers for one machine in a single kas run, one --target per container, instead of one job per (container, machine) pair.

containers.json​

Each entry declares what to build and where it applies:

FieldMeaning
nameContainer name; used in artifact and S3 names
machineMachines that build it (docker-x86_64, docker-armv6, docker-armv8)
build_targetRecipe passed to kas as --target (defaults to name)
outputpvrexport file the build produces, e.g. pv-avahi.pvrexport.tgz
workflowsmanual and/or tag: which dispatch lists and release runs include it
display_name, descriptionShown in containers-releases.json

After editing it, regenerate the workflows and commit both together:

.github/scripts/makeworkflows

The container list for a tag build is resolved at run time, so adding a container to a machine that already builds containers needs no workflow regen (the manual dispatch dropdown does).

Building locally​

.github/scripts/container-targets is the single place that decides which containers build for a machine:

.github/scripts/container-targets docker-armv8
# --target pv-labutils --target pv-avahi --target pvwificonnect ...

./kas-container build $(.github/scripts/container-targets docker-x86_64) \
kas/build-configs/release/containers/docker-x86_64-scarthgap.yaml -- -k

--target flags must come before the config, or kas rejects -- -k. Options:

container-targets --workflow tag <machine> # only containers listed for "tag"
container-targets --container "pv-avahi pv-pvsm" <machine>
container-targets --list name <machine> # one value per line: name|build_target|output

It prints nothing when no container matches, so callers treat empty as an error.

Workflows​

WorkflowTriggerWhat it buildsOutput
manual-containers-scarthgap.yamlworkflow_dispatchmachine + container (default all)One artifact per container
release-containers.yamltag push (via tag-scarthgap.yaml)Every tag container, docker-armv6, then docker-armv8, then docker-x86_64S3 + containers-releases.json
onpush-containers.yamlpush / ready_for_review touching recipes-containers/**Only the containers that changed, on every machine each supportsBranches/PRs: one artifact per container. master: S3 + containers-releases.json under the latest tag

All three build with -k, so one broken recipe doesn't block the rest, and still publish whatever built.

Manual dispatch​

Pick the machine first; container defaults to all. Choosing a container the machine doesn't support (e.g. pv-debian-nm on docker-armv8) fails in the resolve job.

gh workflow run manual-containers-scarthgap.yaml \
-f machine=docker-armv8 -f container=pv-avahi

The build yields one combined artifact; a follow-up split job republishes each pvrexport as <container>-<machine>-scarthgap and removes the combined zip.

Tag release​

release-containers.yaml runs 3 jobs, serialised with max-parallel: 1. Each job uploads every container that built (upload-container.sh) and writes a per-container ✅/❌ table to the job summary. docker-x86_64 is included, so x86_64-only containers such as pv-debian-nm are published too.

upload-container.sh picks the file by the container's declared output (not the first pvrexport found) and exits non-zero if it is missing or the S3 copy fails, which marks that container ❌. Each uploaded container is recorded under its tag in containers-releases.json (at the root of the CI S3 bucket), with the version, pvrexport URL and sha256 per machine. The pvrexports themselves land under containers/<tag>/<container>-<machine>-scarthgap/<container>-<arch>.pvrexport.tgz.

On push​

.github/scripts/changed-containers maps changed paths (stdin) to container names, logging each decision to stderr:

git diff --name-only master...HEAD | .github/scripts/changed-containers

Rules:

  • A file or any parent directory named after a container belongs to it, longest name wins (pv-avahi-browse_1.0.bb → pv-avahi-browse, pv-labutils/packagegroup-pv-labutils.bb → pv-labutils).
  • A shared file matching no name belongs to the containers whose recipes reference its basename (pantavisor/files/mdev.json → pv-alpine-connman pv-awconnect pv-debian-nm).
  • pv-examples/ and debug/ are not shipped containers and are ignored.

Branches with a draft PR are skipped, like onpush-scarthgap; run gh pr ready to build.

On a push to master the changed containers are uploaded instead of kept as artifacts, through the same buildkas-upload-container.yaml as a tag release. They go under the latest release tag reachable from the commit, with version <tag>-<short sha>, and replace that tag's containers-releases.json entry for those machines; the other containers in the release stay as the tag built them. The tag-built pvrexport is not overwritten, as the new one carries the version in its name:

containers/031-rc2/pv-avahi-docker-armv8-scarthgap/pv-avahi-armv8.pvrexport.tgz # tag build
containers/031-rc2/pv-avahi-docker-armv8-scarthgap/pv-avahi-armv8-031-rc2-1fa2225.pvrexport.tgz # master push

To see which build a release currently points at:

aws s3 cp s3://$AWS_S3_BUCKET/containers-releases.json - \
| jq '.["release-candidate"]["031-rc2"].containers[] | select(.name == "pv-avahi") | .machines'

Reusable workflows​

FileRole
buildkas-containers.yamlGenerated. resolve → build → split; called by the manual dispatch and onpush-containers
buildkas-target.yamlbuild_target takes a space-separated list (one --target each); keep_going adds -k
buildkas-upload-container.yamlTag and master builds: kas build, S3 upload and summary table per machine; containers, release and version narrow it for onpush-containers