Skip to main content
Version: master

Build Pipeline

Build Engines​

Two reusable workflows handle all image builds. They share the same runner setup and KAS invocation but differ in what happens with the output. A third, buildkas-sdk.yaml, builds the SDK.

buildkas-target.yaml — development builds​

Used by onpush-scarthgap.yaml, manual-scarthgap.yaml, schedule-pvtests.yaml, and manual-pvtests.yaml.

  • Runs kas build inside the KAS container on a self-hosted runner.
  • Copies build artifacts to GitHub Actions artifacts (wic images, pvrexports, pvtest-distro).
  • Does not upload to S3 and does not create a GitHub Release.

buildkas-upload.yaml — release builds​

Used by release.yaml (tag builds only).

  • Same build steps as buildkas-target.yaml.
  • Additionally calls upload.sh to push artifacts to S3 and update releases.json.

buildkas-sdk.yaml — SDK​

Used by release.yaml (tag builds, publish: true) and manual-sdk-scarthgap.yaml (workflow_dispatch, artifact only), for every machine in sdk_machines in machines.json.

  • Builds with kas/machines/<machine>.yaml:kas/scarthgap.yaml:kas/bsp-base.yaml:kas/sdk.yaml: the board distro (musl, board PANTAVISOR_FEATURES) on a board-less docker-* machine, in build/tmp-scarthgap-sdk.
  • Runs bitbake -c populate_sdk pv-sdk (recipe: dynamic-layers/qt6-layer/recipes-pv/images/pv-sdk.bb, parsed only when meta-qt6 is in the build, as kas/sdk.yaml adds it).
  • Uploads the installer as the pv-sdk-<arch> Actions artifact, renamed pv-sdk-<ref>-<arch>.sh, where <arch> is the machine without its docker- prefix (x86_64, armv8, armv6).
  • Before uploading, runs .github/scripts/sdk-smoke-test on the installer: installs it, packs a container with pv-mkpvrexport, and builds pantavisor at PANTAVISOR_SRCREV.
  • With publish: true, uploads it to s3://<BUCKET>/<tag>/sdk/ with .github/scripts/upload-sdk.sh, beside a pv-sdk-<tag>-<arch>.json entry. The publish-sdks job of release.yaml lists those entries in releases.json once the machine and SDK jobs are done.

Build one by hand from the Actions tab (manual: sdk scarthgap, choosing the arch), or locally:

./kas-container shell kas/machines/docker-armv8.yaml:kas/scarthgap.yaml:kas/bsp-base.yaml:kas/sdk.yaml \
-c "bitbake -c populate_sdk pv-sdk"
ls build/tmp-scarthgap-sdk/deploy/sdk/pv-sdk-armv8-x86_64.sh

Using the SDK: Build Containers with the SDK and Pantavisor SDK.

Runner environment​

DetailValue
Runner labelself-hosted
Container imageghcr.io/pantacor/kas/kas:next-v7
sstate cache/shared/sstate (Docker volume shared)
Download dir/shared/dldir (Docker volume shared)
Build userbuilder (non-root, container switches with su - builder)
Temp dirtmp-scarthgap

Artifacts​

Every build produces some subset of the following:

Artifact nameContentsEngine
<target>-<machine>wic flash image (*.rootfs.wic*)both
pvrexports-<machine>pvrexport tarballs (*pvrexport.tgz)both
pantavisor-bsp-<machine>BSP pvrexport onlyboth
pvtest-distro-<machine>unpacked appengine distro directoryboth
pv-flash-bundle-<machine>UUU factory flash bundle (pv-flash-bundle-*.tar.gz) — Toradex, Variscite, NXP MEKboth
pv-sdk-<arch>SDK installer (pv-sdk-<ref>-<arch>.sh)buildkas-sdk.yaml

USB Factory-Flash Builds (Toradex, Variscite, NXP MEK, Rockchip)​

These machines declare extra_targets in .github/machines.json; makemachines appends them to the release yaml's target: list (there is no per-flavour build-base-*-starter.yaml).

Toradex machines (verdin-imx8mm, colibri-imx6ull) use a multi-target build that produces three artifacts in a single kas build invocation (extra_targets: ["mc:tezi-recovery:u-boot-toradex", "pv-flash-bundle"]):

target:
- pantavisor-starter # main Pantavisor image (wic / ubifs)
- mc:tezi-recovery:u-boot-toradex # recovery U-Boot via tezi-recovery multiconfig
- pv-flash-bundle # self-contained factory flash archive

Variscite machines (imx8mm-var-dart, imx8mn-var-som), the NXP eval board (imx8qxp-b0-mek) and the Rockchip board (rockchip-orangepi-5b) only need two targets — no recovery multiconfig (extra_targets: ["pv-flash-bundle"]). The NXP boards' production bootloader already works for UUU flashing; the Rockchip board flashes over USB Maskrom with rkdeveloptool (see the pv-flash-bundle section below):

target:
- pantavisor-starter # main Pantavisor image (wic)
- pv-flash-bundle # self-contained factory flash archive

tezi-recovery multiconfig​

BBMULTICONFIG = "tezi-recovery" is set by the kas/platforms/toradex.yaml fragment. The multiconfig uses DISTRO = "tezi" (from meta-toradex-tezi) and builds in a separate tmp-scarthgap-tezi-recovery/ tmpdir. It produces the recovery U-Boot artifacts that pv-flash-bundle picks up:

MachineRecovery artifactProduction NAND artifact
verdin-imx8mmimx-boot-recoverytezi— (eMMC, no separate NAND binary)
colibri-imx6ullu-boot.imx-recoveryteziu-boot.imx-rawnand

meta-toradex-tezi is masked (via BBMASK) in the main panta-distro build to prevent Tezi-specific recipes from conflicting. Only the recipes-bsp/ U-Boot bbappends are active in the main build context.

pv-flash-bundle​

recipes-bsp/pv-flash/pv-flash-bundle.bb assembles a self-contained archive that operators use for factory flashing:

MachineImage payloadFlash method
verdin-imx8mm.wic.gz (eMMC)SDP + SDPV → fastboot → FB: flash -raw2sparse all
colibri-imx6ull.ubifs (NAND)SDP → fastboot → nand write + ubi write
imx8mm-var-dart.wic.gz (eMMC)SDP + SDPV → fastboot → FB: flash -raw2sparse all
imx8mn-var-som.wic.gz (eMMC)SDP + SDPV → fastboot → FB: flash -raw2sparse all
imx8qxp-b0-mek.wic.gz (eMMC)SDPS (stream mode) → fastboot → FB: flash -raw2sparse all

Toradex differs from the other three in where the boot binary comes from: Toradex needs a stripped recovery U-Boot from the tezi-recovery multiconfig (PV_FLASH_RECOVERY_MC/_RECIPE/_IMAGE), because its production bootcmd is overridden by meta-pantavisor's pv.distroboot.cfg. Variscite's imx8mm-var-dart/imx8mn-var-som and NXP's own imx8qxp-b0-mek don't need a second multiconfig — their production imx-boot already self-enters SDP/fastboot mode at the SPL/ROM level regardless of bootcmd, so pv-flash-bundle just globs it straight out of the main build's deploy dir via PV_FLASH_BOOT_IMAGE. imx8qxp-b0-mek additionally differs in protocol, not just boot-binary source: i.MX8QXP silicon uses SDPS: stream mode instead of SDP:/SDPV: (see pv-flash-bundle for why). See docs/how-to-install/toradex.md for the Toradex flashing procedure, and docs/how-to-install/uuu.md for Variscite/MEK.

S3 Distribution (upload.sh)​

upload.sh is called by buildkas-upload.yaml once per machine. It:

  1. Bundles the wic image and pvrexports into a tarball.
  2. Pushes the bundle to s3://<BUCKET>/meta-pantavisor/<TAG>/<MACHINE>/.
  3. Reads the existing releases.json from S3, upserts the machine entry under devices, sets release-date on first write, and uploads the file back.

releases.json is the discovery index used by the Pantavisor ecosystem to find the latest image URLs and SHA256 checksums. Schema:

{
"stable": {
"029": {
"release-date": "2026-06-03T10:00+00:00",
"docs": {
"name": "pantavisor-<rest>.docs.tar.zst",
"hash": "<sha256>",
"url": "https://pantavisor-ci.s3.amazonaws.com/meta-pantavisor/029/pantavisor-<rest>.docs.tar.zst"
},
"devices": [
{
"name": "raspberrypi-armv8-scarthgap",
"display_name": "Raspberry Pi 3 / 4 (64-bit)",
"description": "64-bit ARMv8 build for the Raspberry Pi 3 and 4.",
"full_image": { "url": "https://.../029/raspberrypi-armv8-scarthgap/raspberrypi-armv8-scarthgap-029.tar.gz", "sha256": "<sha256>" },
"pvrexports": { "url": "https://.../pvexports-raspberrypi-armv8-scarthgap-029.tar.gz", "sha256": "<sha256>" },
"bsp": { "url": "https://.../pantavisor-bsp-....pvrexport.tgz", "sha256": "<sha256>" }
}
]
}
},
"release-candidate": {
"029-rc1": {
"release-date": "2026-05-30T08:00+00:00",
"docs": { "name": "...", "hash": "...", "url": "..." },
"devices": [ "..." ]
}
}
}

release-date is set by the first machine job to finish (using //=) and left unchanged by subsequent parallel jobs. The docs key is written later by tag-docs-scarthgap.yaml.

sdks is written by the publish-sdks job, one entry per installer, and is absent from releases without SDKs (anything before 031-rc3):

"sdks": [
{
"release": "031-rc6",
"platform": "linux/arm64",
"arch": "armv8",
"url": "https://pantavisor-ci.s3.amazonaws.com/meta-pantavisor/031-rc6/sdk/pv-sdk-031-rc6-armv8.sh",
"sha256": "<sha256>",
"manifests": {
"target": "https://pantavisor-ci.s3.amazonaws.com/meta-pantavisor/031-rc6/sdk/pv-sdk-031-rc6-armv8.target.manifest",
"host": "https://pantavisor-ci.s3.amazonaws.com/meta-pantavisor/031-rc6/sdk/pv-sdk-031-rc6-armv8.host.manifest"
},
"contents": {
"toolchain": { "gcc": "<version>", "musl": "<version>", "...": "..." },
"host": { "cmake": "<version>", "pvr": "<version>", "...": "..." },
"target": { "openssl": "<version>", "qtbase": "<version>", "...": "..." }
}
}
]

contents and manifests come from files pv-sdk.bb writes next to the installer. contents is a summary by recipe and upstream version: toolchain is the cross compilers and the C library, host what nativesdk-pv-sdk-tools pulls in, and target what packagegroup-pv-sdk-target pulls in (packagegroups are expanded). The two manifests list every installed package as <package> <arch> <version>, under the Debian-renamed package names (libz-dev for zlib-dev). Installers built before the summary existed (up to 031-rc8) have neither key. To list a release's SDK contents:

curl -s https://pantavisor-ci.s3.amazonaws.com/meta-pantavisor/releases.json \
| jq '.["release-candidate"]["<tag>"].sdks[] | {arch, contents}'

To publish an installer by hand, for example one from manual: sdk scarthgap or a tag whose publish-sdks job failed, run both steps with AWS credentials in the environment. index replaces the tag's whole sdks list with what is under <tag>/sdk/, and should not run while a tag build is uploading:

.github/scripts/upload-sdk.sh upload pantavisor-ci/meta-pantavisor <tag> armv8 pv-sdk-<tag>-armv8.sh
.github/scripts/upload-sdk.sh index pantavisor-ci/meta-pantavisor <tag>

display_name and description are the friendly board label and blurb shown on the downloads list. upload.sh reads them from the machine's entry in .github/machines.json (matching on the slug with the -<yocto_branch> suffix stripped); display_name falls back to the suffixed slug and description is omitted when unset.

S3 path layout​

s3://<BUCKET>/meta-pantavisor/
<tag>/
<machine>/ ← bundle for this specific tag + machine
pantavisor-<rest>.docs.tar.zst ← combined docs tarball for this tag
latest/
stable/
badges/ ← per-machine badge JSON, updated after every stable tag build
release-candidate/
badges/ ← per-machine badge JSON, updated after every RC tag build

Stable vs release-candidate classification​

upload.sh and upload-badges both check whether the tag contains -rc:

Tag patternClassificationS3 latest path
028, 029stablelatest/stable/
028-rc1, 028-rc9release-candidatelatest/release-candidate/

Shared Build (build-docs-scarthgap.yaml)​

build-docs-scarthgap.yaml is a workflow_call reusable workflow — the same pattern as buildkas-target.yaml — that both tag-docs-scarthgap.yaml and docs-scarthgap.yaml call for the actual build. It takes ref (git ref to build), fetch_tags (whether to fetch all tags first), and artifact_name (name for the uploaded tarball artifact) as inputs, and does:

  1. Checks out ref.
  2. Optionally fetches all tags (fetch_tags: true), needed by the tag build so git describe-based versioning sees the release tag.
  3. Resets the workspace to ref (via git fetch origin $EFFECTIVE_REF && git reset --hard FETCH_HEAD, which works for both branch names and commit SHAs).
  4. Runs kas build kas/build-configs/release/raspberrypi-armv8-scarthgap.yaml -- -c create_pantacor_docs pantavisor-starter inside the KAS container. raspberrypi-armv8-scarthgap.yaml was chosen because pantavisor-starter is its primary target and it pulls in the full set of components — including pvr (shipped in the pvr-sdk container) — that need documentation. The pantavisor-docs image class triggers do_create_component_docs for every package in the image's dependency tree (via [recrdeptask]), collects the resulting per-component tarballs, adds meta-pantavisor/docs/, and packages everything into a single <IMAGE_LINK_NAME>.rootfs.docs.tar.zst. No full image assembly is needed — BitBake only builds packages up to do_install.
  5. Collects the real tarball (non-symlink *.rootfs.docs.tar.zst) from build/tmp-scarthgap/deploy/images/raspberrypi-armv8/.
  6. Uploads it as a workflow artifact (actions/upload-artifact) named artifact_name, for the calling workflow's publish job to download.

Documentation is built using pantavisor-docs.bbclass and pantacor-component-docs.bbclass. See how-to-build/component-docs.md for the full class reference.

Documentation Tarball (tag-docs-scarthgap.yaml)​

tag-docs-scarthgap.yaml runs via workflow_run after the ontag: sync and release workflow (tag-scarthgap.yaml) completes successfully. It is independent of the per-machine build matrix.

It has two jobs: build-docs, which calls build-docs-scarthgap.yaml with ref: workflow_run.head_sha (the tagged commit) and fetch_tags: true; and publish-docs (needs: build-docs, runs on ubuntu-latest), which downloads the artifact and:

  1. Renames the tarball: pantavisor-starter-<rest>.rootfs.docs.tar.zst → pantavisor-<rest>.docs.tar.zst (strips starter- and .rootfs).
  2. Uploads the renamed tarball directly under the tag prefix in S3:
    s3://<BUCKET>/meta-pantavisor/<TAG>/pantavisor-<rest>.docs.tar.zst
  3. Downloads releases.json from S3, upserts a docs key at the tag level, and writes it back. Machine entries written by upload.sh live under devices in the same object:
{
"release-candidate": {
"028-rc10": {
"release-date": "2026-05-13T21:27+00:00",
"docs": {
"name": "pantavisor-<rest>.docs.tar.zst",
"hash": "<sha256>",
"url": "https://pantavisor-ci.s3.amazonaws.com/meta-pantavisor/028-rc10/pantavisor-<rest>.docs.tar.zst"
},
"devices": [
{ "name": "sunxi-orange-pi-3lts-scarthgap", "full_image": {}, ... },
...
]
}
}
}
  1. Uploads the original (unstripped) tarball to the GitHub Release via upload-docs.py upload-asset, then sends a repository_dispatch event (event_type: "docs-release", payload {"tag": "<TAG>"}) directly to pantavisor/docs.pantavisor via curl using the PANTAVISOR_DOCS_SYNC secret.

The tag is taken from workflow_run.head_branch (the tag that triggered tag-scarthgap.yaml). Because workflow_run only fires for workflow files present on the default branch, this workflow takes effect once it is on master.

Latest Documentation Build (docs-scarthgap.yaml)​

docs-scarthgap.yaml is a push/workflow_dispatch counterpart to tag-docs-scarthgap.yaml. It generates the latest documentation tarball from the master branch whenever docs/ files change on master, or on demand via manual dispatch (unlike the tag-triggered workflow, which only runs on tagged releases).

It shares the build-docs-scarthgap.yaml build with tag-docs-scarthgap.yaml and follows the same two-job shape: build-docs calls the reusable workflow with ref: master (always builds the latest master tip, ignoring the triggering commit/ref) and fetch_tags: false (default); publish-docs (needs: build-docs, runs on ubuntu-latest) downloads the artifact and:

  1. Renames the tarball: pantavisor-starter-<rest>.rootfs.docs.tar.zst → pantavisor-<rest>.docs.tar.zst (strips starter- and .rootfs).
  2. Uploads the renamed tarball to the docs/latest/ prefix in S3:
    s3://<BUCKET>/meta-pantavisor/docs/latest/pantavisor-<rest>.docs.tar.zst
  3. Writes a latest.json metadata file to s3://<BUCKET>/meta-pantavisor/docs/latest.json:
{
"name": "pantavisor-<rest>.docs.tar.zst",
"hash": "<sha256>",
"url": "https://pantavisor-ci.s3.amazonaws.com/meta-pantavisor/docs/latest/pantavisor-<rest>.docs.tar.zst",
"branch": "master",
"generated": "<ISO 8601 timestamp>"
}

Unlike tag-docs-scarthgap.yaml, this workflow does not upload to GitHub Releases, and it does not send a repository_dispatch to docs.pantavisor — that notification only happens on tagged releases.

CI Badges (upload-badges)​

After all build jobs finish, the summary job in release.yaml calls upload-badges. The script:

  1. Queries the GitHub API for all jobs in the current run that match contains("build (").
  2. Maps each job's conclusion to a shields.io color (brightgreen / red / lightgrey / yellow).
  3. Writes a JSON file per machine: {"schemaVersion":1,"label":"<machine>","message":"passing","color":"brightgreen"}.
  4. Uploads each JSON to s3://<BUCKET>/meta-pantavisor/latest/<stable|release-candidate>/badges/<machine>.json.
  5. Uploads a tag.json badge showing the tag name.

The badge URLs in README.md and docs/ci/status.md point to these S3 objects via https://img.shields.io/endpoint?url=<S3-URL>. Shields.io fetches the JSON on render and produces an SVG badge.

pvtests Pipeline​

pvtests run against the docker-x86_64-scarthgap appengine distro image. They require a dedicated pvtest-runner runner with Docker available.

The call-pvtests.yaml reusable workflow:

  1. Downloads the pvtest-distro-docker-x86_64-scarthgap artifact.
  2. Installs Docker images via test.docker.sh install-docker.
  3. Runs test.docker.sh run <test_path> (no retries — failures surface directly).
  4. Appends the SUMMARY section of test.docker.log to the step summary.
  5. Uploads the pvtest workspace (logs, valgrind output) as an artifact.
  6. Cleans up Docker containers and images.

test_path controls which tests run:

  • local — tests that run entirely on the runner (no network to Pantahub)
  • remote — tests that connect to Pantahub (require PH_USER/PH_TOKEN secrets, a Pantahub personal token)
  • empty — run all tests

In release.yaml, pvtest-remote runs with if: always() so it executes even if pvtest-local fails, and its results don't block the summary job.

CI coverage​

In order to limit the time usage of the CI runners, we run the smallest set of tests (by scope) possible that ensures the right coverage based on the changes to be verified.

Changed fileslocal volatilelocal persistentremote volatileremote persistent
recipes-pv/pantavisor/pantavisor.inc✓✓✓✓
recipes-containers/pv-examples/✓✓✓✓
recipes-pv/pvr/✓✓✓✓
pantavisor-appengine-distro.bb, pantavisor-appengine-tester.bb✓✓✓✓
any other file outside docs/ and CHANGELOG/✓

The nightly schedule-pvtests.yaml runs every scope and model. Remote tests run against both the prod and the stage Hub. Local tests never talk to the Hub, so they run against prod only.

Component Auto-Updates​

schedule-updates.yaml runs update-components.sh every 8 hours. The script reads .github/scripts/components.json, which lists each tracked component with its recipe glob and GitHub org. For each component:

  1. Fetches the latest commit SHA via git ls-remote from the branch the recipe itself names: branch= in SRC_URI, or a <NAME>_BRANCH default such as PANTAVISOR_BRANCH in pantavisor.inc. Moving a recipe to a new branch is all it takes for the updater to follow it.
  2. If the SHA differs from the current SRCREV in the recipe, updates the recipe in-place.
  3. Appends a short git log to the commit message body for review.

If any updates were found, the workflow opens (or force-updates) a PR on auto-update/components.

Pantavisor Docs Check (onpush-pantavisor-docs.yaml)​

The docs tarball built by docs-scarthgap.yaml embeds pantavisor's own docs/ folder, pulled from its source tree at whatever commit PANTAVISOR_SRCREV (in recipes-pv/pantavisor/pantavisor.inc) pins. A PANTAVISOR_SRCREV bump — whether from schedule-updates.yaml or a manual edit — doesn't touch meta-pantavisor/docs/**, so it wouldn't otherwise trigger a docs rebuild even if it moves past commits that changed docs/ in the pantavisor repo itself.

onpush-pantavisor-docs.yaml closes that gap. It triggers on push to master when recipes-pv/pantavisor/pantavisor.inc changes, and:

  1. Reads the new PANTAVISOR_SRCREV from the pushed commit, and the old one from github.event.before (via git show <before>:pantavisor.inc).
  2. If they differ, does a throwaway shallow clone of https://github.com/pantavisor/pantavisor.git (public, no auth needed — same pattern as update-components.sh), fetching both SRCREVs and running git diff --name-only <old> <new> -- docs/.
  3. If docs/ changed upstream, dispatches docs-scarthgap.yaml via gh workflow run docs-scarthgap.yaml --ref master. Since both workflows live in this repo, this uses the default GITHUB_TOKEN (granted actions: write) rather than a cross-repo PAT.

If the previous SRCREV or the upstream commits can't be resolved (e.g. a shallow-history edge case), the job triggers the docs build anyway rather than risk silently skipping a real docs update.

This check is scoped to pantavisor only — not generalized to the other components.json entries.