Secrets, tokens and signing

Builds of public repositories need nothing but a login. Private repositories, private Yocto layers and release signing use account secrets: credentials you store once in the Hub, which builds use on your behalf. Their values are write-only — the Hub, pvr and the UI only ever show a secret's name, type and where it may be sent.

Secret types

Type	Holds	Used for
git	A repository token (GitHub personal access token, GitLab access token) and an optional user name	Fetching a private repository, and, when named, a recipe's private layers and sources
registry	A container registry user name and password or token	Registry logins
pvs	A PEM private key and its certificate chain	Signing exports with your key
config	One value, such as a device join token	A value of a build's OEM configuration part

Each secret also has:

• Hosts (--host, "May be sent to"): where it may be sent, as a host and optional path — github.com/acme covers every repository of acme, github.com/acme/sdk only that one. A secret is never sent anywhere else.
• Refs (optional, git and pvs only): the branches and tags it may be used for, as patterns (main, release/*, v*). tags/<pattern> matches only tags and heads/<pattern> only branches; a bare pattern matches both, so v* also lets a branch named v1-test use the secret. A build of another ref, or of a bare commit, cannot use it. Empty allows every ref.

Adding secrets

In the web UI: user menu → Secrets (/settings/secrets) → Add secret. Pick the type, give it a name, the hosts, optionally the refs, and paste the value. Edit replaces any field; the value only when you type a new one.

With pvr (the value is read from standard input or a hidden prompt, never from the command line):

# A GitHub token for every private repository of acme
pvr secret add --type git --host github.com/acme --description "acme repos" gh-acme

# A signing key: the PEM private key followed by its certificate chain
cat key.pem chain.pem | pvr secret add --type pvs --host github.com/acme/my-app release-key

pvr secret ls                                  # names, types, hosts, last use
pvr secret set --host github.com/acme --host gitlab.com/acme gh-acme
pvr secret set --value gh-acme                 # rotate the value
pvr secret rm gh-acme

For stage, run pvr with -b https://api.stage.pantahub.com (or export PVR_BASEURL=https://api.stage.pantahub.com).

How a build picks its secrets

	Not named in the build	Named in the build (secret)
Fetching the repository	The account's git secret whose hosts match the repository	That secret (it must match the repository)
A Yocto/Buildroot recipe's own fetches	None	That secret, for its hosts only
Signing (signing_secret)	pvr's public developer key	That pvs key

Secrets in recipe builds

Yocto and Buildroot recipes run code from your repository and from the layers it pulls in, and that code can read whatever credentials it is given. So a recipe only gets the git secret you name in the build — the automatic choice fetches your repository and nothing else. Name it when a kas file includes a private layer or a recipe's SRC_URI points at a private repository:

• Web UI: App name and secrets → Git secret
• pvr: --secret gh-acme
• GitHub Actions: secret: gh-acme

Without it, a private fetch fails while BitBake parses or fetches, with could not read Username for 'https://github.com' in the log.

The recipe receives it as a git configuration that adds the credential only for the secret's hosts. Give the secret hosts that cover exactly the private repositories the build needs, and prefer a read-only token.

Signing

Every export is signed, so a device that verifies signatures can install it — but with which key is your choice:

• Developer key (default). pvr's well-known public development key. Fine for development devices; anyone can sign with it, so a device configured for release keys refuses it. The build's summary shows Developer key — not for release.
• A signing identity. The easiest way to sign with your own key: the Hub makes (or you upload) the roots and keys, and gives you the image settings that trust them. See Signing identities.
• Your key. Add a pvs secret and name it in the build (signing_secret, Signing key in the form). Only a key you name signs: release signing never happens as a side effect. Limit the secret's refs to your release tags (tags/v*) so only those can be signed with it: a bare v* would also match a branch of that name.

The summary and the GitHub job summary show which key signed each export, and the artifact's sha256.

Tokens

The web UI and pvr login use your session. For scripts and CI, create a personal token under Tokens (/tokens/new) with the access it needs:

Scope	Allows
builds.write	Starting, cancelling and retrying builds of public sources, signed with the developer key. Naming a secret is refused.
builds.readonly	Listing builds and reading their logs and status.
objects.readonly	Downloading exports.
builds (or api, all)	Everything above, plus using the account's secrets: private repositories and your signing key.
secrets.readonly / secrets.write	Seeing / managing the secrets themselves (not needed to build).

A GitHub workflow building a private repository therefore needs a token with builds and objects.readonly.

Treat tokens and secret values like passwords. Rotate a token or secret that has been shown anywhere public; pvr secret set --value replaces a value without changing the secret's name.