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 buildinside 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.shto push artifacts to S3 and updatereleases.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, boardPANTAVISOR_FEATURES) on a board-lessdocker-*machine, inbuild/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, askas/sdk.yamladds it). - Uploads the installer as the
pv-sdk-<arch>Actions artifact, renamedpv-sdk-<ref>-<arch>.sh, where<arch>is the machine without itsdocker-prefix (x86_64,armv8,armv6). - Before uploading, runs
.github/scripts/sdk-smoke-teston the installer: installs it, packs a container withpv-mkpvrexport, and builds pantavisor atPANTAVISOR_SRCREV. - With
publish: true, uploads it tos3://<BUCKET>/<tag>/sdk/with.github/scripts/upload-sdk.sh, beside apv-sdk-<tag>-<arch>.jsonentry. Thepublish-sdksjob ofrelease.yamllists those entries inreleases.jsononce 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
| Detail | Value |
|---|---|
| Runner label | self-hosted |
| Container image | ghcr.io/pantacor/kas/kas:next-v7 |
| sstate cache | /shared/sstate (Docker volume shared) |
| Download dir | /shared/dldir (Docker volume shared) |
| Build user | builder (non-root, container switches with su - builder) |
| Temp dir | tmp-scarthgap |
Artifacts
Every build produces some subset of the following:
| Artifact name | Contents | Engine |
|---|---|---|
<target>-<machine> | wic flash image (*.rootfs.wic*) | both |
pvrexports-<machine> | pvrexport tarballs (*pvrexport.tgz) | both |
pantavisor-bsp-<machine> | BSP pvrexport only | both |
pvtest-distro-<machine> | unpacked appengine distro directory | both |
pv-flash-bundle-<machine> | UUU factory flash bundle (pv-flash-bundle-*.tar.gz) — Toradex, Variscite, NXP MEK | both |
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:
| Machine | Recovery artifact | Production NAND artifact |
|---|---|---|
| verdin-imx8mm | imx-boot-recoverytezi | — (eMMC, no separate NAND binary) |
| colibri-imx6ull | u-boot.imx-recoverytezi | u-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:
| Machine | Image payload | Flash 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:
- Bundles the wic image and pvrexports into a tarball.
- Pushes the bundle to
s3://<BUCKET>/meta-pantavisor/<TAG>/<MACHINE>/. - Reads the existing
releases.jsonfrom S3, upserts the machine entry underdevices, setsrelease-dateon 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 pattern | Classification | S3 latest path |
|---|---|---|
028, 029 | stable | latest/stable/ |
028-rc1, 028-rc9 | release-candidate | latest/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:
- Checks out
ref. - Optionally fetches all tags (
fetch_tags: true), needed by the tag build sogit describe-based versioning sees the release tag. - Resets the workspace to
ref(viagit fetch origin $EFFECTIVE_REF && git reset --hard FETCH_HEAD, which works for both branch names and commit SHAs). - Runs
kas build kas/build-configs/release/raspberrypi-armv8-scarthgap.yaml -- -c create_pantacor_docs pantavisor-starterinside the KAS container.raspberrypi-armv8-scarthgap.yamlwas chosen becausepantavisor-starteris its primary target and it pulls in the full set of components — includingpvr(shipped in the pvr-sdk container) — that need documentation. Thepantavisor-docsimage class triggersdo_create_component_docsfor every package in the image's dependency tree (via[recrdeptask]), collects the resulting per-component tarballs, addsmeta-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 todo_install. - Collects the real tarball (non-symlink
*.rootfs.docs.tar.zst) frombuild/tmp-scarthgap/deploy/images/raspberrypi-armv8/. - Uploads it as a workflow artifact (
actions/upload-artifact) namedartifact_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:
- Renames the tarball:
pantavisor-starter-<rest>.rootfs.docs.tar.zst→pantavisor-<rest>.docs.tar.zst(stripsstarter-and.rootfs). - Uploads the renamed tarball directly under the tag prefix in S3:
s3://<BUCKET>/meta-pantavisor/<TAG>/pantavisor-<rest>.docs.tar.zst
- Downloads
releases.jsonfrom S3, upserts adocskey at the tag level, and writes it back. Machine entries written byupload.shlive underdevicesin 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": {}, ... },
...
]
}
}
}
- Uploads the original (unstripped) tarball to the GitHub Release via
upload-docs.py upload-asset, then sends arepository_dispatchevent (event_type: "docs-release", payload{"tag": "<TAG>"}) directly topantavisor/docs.pantavisorviacurlusing thePANTAVISOR_DOCS_SYNCsecret.
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:
- Renames the tarball:
pantavisor-starter-<rest>.rootfs.docs.tar.zst→pantavisor-<rest>.docs.tar.zst(stripsstarter-and.rootfs). - Uploads the renamed tarball to the
docs/latest/prefix in S3:s3://<BUCKET>/meta-pantavisor/docs/latest/pantavisor-<rest>.docs.tar.zst - Writes a
latest.jsonmetadata file tos3://<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:
- Queries the GitHub API for all jobs in the current run that match
contains("build ("). - Maps each job's conclusion to a shields.io color (
brightgreen/red/lightgrey/yellow). - Writes a JSON file per machine:
{"schemaVersion":1,"label":"<machine>","message":"passing","color":"brightgreen"}. - Uploads each JSON to
s3://<BUCKET>/meta-pantavisor/latest/<stable|release-candidate>/badges/<machine>.json. - Uploads a
tag.jsonbadge 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:
- Downloads the
pvtest-distro-docker-x86_64-scarthgapartifact. - Installs Docker images via
test.docker.sh install-docker. - Runs
test.docker.sh run <test_path>(no retries — failures surface directly). - Appends the SUMMARY section of
test.docker.logto the step summary. - Uploads the pvtest workspace (logs, valgrind output) as an artifact.
- 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 (requirePH_USER/PH_TOKENsecrets, 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 files | local volatile | local persistent | remote volatile | remote 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:
- Fetches the latest commit SHA via
git ls-remotefrom the branch the recipe itself names:branch=inSRC_URI, or a<NAME>_BRANCHdefault such asPANTAVISOR_BRANCHinpantavisor.inc. Moving a recipe to a new branch is all it takes for the updater to follow it. - If the SHA differs from the current
SRCREVin the recipe, updates the recipe in-place. - 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:
- Reads the new
PANTAVISOR_SRCREVfrom the pushed commit, and the old one fromgithub.event.before(viagit show <before>:pantavisor.inc). - If they differ, does a throwaway shallow clone of
https://github.com/pantavisor/pantavisor.git(public, no auth needed — same pattern asupdate-components.sh), fetching both SRCREVs and runninggit diff --name-only <old> <new> -- docs/. - If
docs/changed upstream, dispatchesdocs-scarthgap.yamlviagh workflow run docs-scarthgap.yaml --ref master. Since both workflows live in this repo, this uses the defaultGITHUB_TOKEN(grantedactions: 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.