Skip to main content
Version: master

Remote builds (pvr build)

Development preview for Pantahub Builder. Submit a simulated execution or package a digest-pinned registry image as a pvr export. Dockerfile builds, Yocto images, reviewed production plans, and subscription admission remain pending. Development executions are unbilled.

Connect to the local HTTPS Hub​

Start the cluster with hub/tls-local.sh on. The full Hub stack requires valid credentials for its private GitLab container images. Configure pvr for the API hostname printed by that command, and trust the local mkcert CA:

export PVR_BASEURL=https://api.<ip-dashed>.sslip.io
export SSL_CERT_FILE=/absolute/path/to/hub/api/.certs/rootCA.pem
export PVR_DISABLE_SELF_UPGRADE=1
pvr login

Existing pvr login/cache/refresh and .netrc authentication are reused. You can instead provide a normal REST token through PVR_ACCESSTOKEN. It needs builds, or both builds.write and builds.readonly scopes. MCP tokens cannot be used on this REST surface. Build calls refuse redirects with credentials. Global flags such as --baseurl and --access-token go before build.

Start and inspect​

pvr build start --project demo --target rpi4 \
--mode simulated --limit-seconds 60 --simulated-seconds 8 \
--idempotency-key demo-first-build

pvr build list
pvr build list --project demo
pvr build list --project demo --artifacts-only
pvr build usage
pvr build status <execution-id>
pvr build logs <execution-id>

start prints execution JSON including its id. Project and target are currently metadata identifiers; no project creation is required. The limit is a runner execution ceiling, excluding queue time. Simulation accepts --simulate-failure; use a shorter execution limit than simulation duration to exercise timeout.

Use a new idempotency key for a new build. Reuse the same key and exact configuration after a lost submission response to retrieve the original execution. If omitted, pvr generates a key and prints it to stderr before submission so it can be recovered. Status and logs are JSON snapshots; log snapshots contain the most recent 128 entries. Poll status until it becomes succeeded, failed, timed_out, or cancelled.

Download or cancel​

pvr build download --output ./demo-artifacts.tar.gz <execution-id>
pvr build cancel <execution-id>

Download requires success, verifies SHA-256, and publishes a new file only after verification. It never overwrites existing files or extracts archives. An artifact is at most 5 GiB. Simulated builds produce simulation.tar.gz (non-deployable); registry and git builds produce <app>.pvrexport.tgz, where the app is named after the image (or the repository of a git build) unless --app names it.

Cancellation returns execution JSON. A running execution may show cancel_requested: true until the runner has stopped it; check status again.

Registry-to-pvr exports​

Enable the registry worker and PH_BUILDER_ALLOW_LOCAL_DOCKER=true as described in the builder's docs/development.md, then submit:

pvr build start --project demo --target rpi4 --mode docker \
--image 'registry.example.com/app@sha256:<64-lowercase-hex-digest>' \
--platform linux/arm64 --limit-seconds 300 \
--idempotency-key demo-registry-build

Supported platforms are linux/arm64, linux/amd64 and linux/arm/v6. This imports an image; it does not run the image or upload/build your current source directory.

Private repositories (pvr secret)​

Builds fetch private Git repositories with the account's secrets. A secret names the hosts and paths it may be sent to; a build uses the one that covers its repository most specifically, or the one named with --secret. Values are write-only: give them on stdin or at the hidden prompt, never as a flag.

pvr secret add acme-github --type git --host github.com/acme < token.txt
pvr secret ls
pvr build start --project app --git-url https://github.com/acme/app --git-ref main
pvr build start --project app --git-url https://github.com/acme/app --secret acme-github
printf '%s\n' "$NEW_TOKEN" | pvr secret set acme-github --value
pvr secret rm acme-github

--host takes a host and optional path (github.com, github.com/acme, gitlab.com/group/sub) and repeats. The builder sends the token only to the repository URL being fetched, never into the Dockerfile build, and masks it in build logs. The same secrets are managed in the web app under Secrets.

Artifacts​

A build's artifact is an object of your account, like the objects of a revision: it counts against the account's storage and stays until deleted. pvr build download <id> saves it under its own name (for example pv-mqtt-sdk.pvrexport.tgz; --output to choose another, --name when a build has several), checked against its sha256. It downloads from a signed object URL, which never receives your credentials.

One pipeline, several architectures​

pvr build start --project mqtt-sdk \
--git-url https://github.com/pantavisor/pv-mqtt-sdk.git \
--git-ref <pinned-commit> --platform amd64,arm64,arm32v6 \
--limit-seconds 600

pvr build status <pipeline-id>
pvr build logs <pipeline-id>
pvr build download --platform arm64 <pipeline-id>
pvr build cancel <pipeline-id>

One API request creates one parent pipeline with a child execution for each architecture. Short names map to linux/amd64, linux/arm64, linux/arm/v6; full platform strings also work. Duplicate targets are collapsed. The source is resolved once, so every child uses the same commit. The execution limit applies to each child, and parent usage is the sum of their measured seconds.

Use an account Git secret for the private repository. pv-mqtt-sdk already cross-compiles these targets in its Dockerfile/build script. Other Dockerfiles need native builders or emulation when running foreign-architecture commands. Children queue behind a single runner; parallel execution needs more runner capacity. Status includes each child's ID, architecture, status and usage.

Downloading a pipeline requires --platform when more than one artifact is available. Default filenames include the architecture to avoid collisions. A failed pipeline can still deliver successful children's artifacts. Cancelling the parent requests cancellation for every unfinished child.

In the Hub, open Builds → New pipeline, enter comma-separated architectures, and submit. The pipeline summary links to each child; its Artifacts tab offers architecture-specific downloads.