Skip to content

Install the Pigsty Repository Key Automatically

Prepare the Pigsty key best-effort, reuse existing files, and fall back with a warning unless repository metadata explicitly names a key.

Decision date: 2026-10-04
Status: Released in v1.9.0. The 2026-11-11 APT trust-reconciliation refinement is implemented in a95f37f, without a release claim.
Current reference: pig repo
Scope: Installing the existing embedded Pigsty public key during repository configuration.

Decision

When a selected module contains an available pigsty-infra or pigsty-pgsql repository, prepare the embedded Pigsty public key before changing repository definitions. Apply this in the shared configuration workflow so repo add, repo set, and callers that reuse it agree. Reuse an existing key file. Automatic installation is best-effort; an explicit signing-key reference in selected repository metadata makes installation failure fatal.

Context

The source baseline installed the key only when a caller requested GPGCheck, as native sty boot does. Ordinary repo add/set therefore omitted a public key already shipped inside PIG.

The key is needed by both Pigsty repositories. Their membership spans pigsty, infra, pgsql, and the default all selection, so checking only the literal argument pigsty would miss normal usage.

APT does not discover files under /etc/apt/keyrings automatically. A repository must reference the prepared file with signed-by; otherwise a successful write still leaves NO_PUBKEY warnings during cache refresh.

Removing signed-by during fallback can conflict with a retained definition of the same APT source. Keep the default reference stable across successful preparation and fallback. Explicit metadata names a required key of its own; preparing an unrelated default file cannot satisfy it.

Alternatives considered

  • Download the default key at runtime. The embedded release input already supplies it and works offline, without adding a network or external-tool dependency.
  • Install the key on every repository operation. Unrelated repositories should not cause a Pigsty key write. Resolve membership and platform availability first.
  • Fail every repository operation when automatic key installation fails. Rejected because optional key preparation should not prevent the existing compatibility mode from working. Explicit signing-key metadata remains a strict boundary.
  • Enable all signature checks at the same time. Publisher identity, RPM package signatures, and APT metadata authentication are separate contracts. Automatic key installation does not establish signing coverage for every package or mirror.

Contract

  • Validate requested modules before installing the key. A rejected replacement does not install it or move repository files.
  • Match the two Pigsty repository identifiers in resolved modules, including custom modules; the URL’s hostname alone does not select a signing identity.
  • Write the existing embedded key to /etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty on EL or /etc/apt/keyrings/pigsty.asc on Debian/Ubuntu when installation is needed, with mode 0644.
  • Check for an existing regular key file first, including a symlink resolving to one; reuse it without changing its contents or permissions. If the existence check fails, attempt installation.
  • Create missing parent directories through the existing sudo fallback and use the atomic file writer. A denied destination check must still reach the privileged attempt, which checks the destination again. An occupied directory or dangling symlink is an installation error.
  • Without explicit key metadata, installation failure warns and continues. Only selected Pigsty definitions fall back to APT trusted=yes or RPM gpgcheck=0 and repo_gpgcheck=0. Fill the default gpgkey or signed-by reference on both success and failure. Do not rewrite retained repository files to implement fallback.
  • Explicit key preparation applies to the actual reference. APT signed-by accepts absolute paths to existing regular keyring files, separated by commas; install the embedded key when the default path is explicitly named. EL prepares an explicitly named default file if needed and passes gpgkey paths or literal URLs to native rpm --import.
  • Failure to prepare an explicit key is fatal before backup, repository writes, or cache refresh. Preserve its reference and never downgrade that definition. A valid custom key does not depend on the default path; an implicit-key failure in another selected repository affects only that implicit definition.
  • Successful ordinary operations preserve signature-checking settings. sty boot requests signing on successful key preparation and follows the same implicit-key fallback on failure.
  • Put fallback warnings on stderr and in repo add/set’s data.warnings; sty boot retains them in its own warnings. Implicit installation does not import into RPM’s database; explicit EL metadata does. Neither path changes APT’s global trust store.
  • Repository rollback restores definitions; already installed or imported public keys remain.

The 2026-11-11 refinement reconciles APT release-level trust by URI and suite before repository writes. Implicit defaults inherit an existing matching source’s trust settings, including when another module selects it or the same module is added again after sty boot. Retained files are never rewritten to implement fallback. Explicit metadata cannot silently override a conflicting retained policy; inconsistent definitions are rejected with guidance to reconcile or replace them. Replacement uses the requested policy after the existing backup step. New definitions selected through several modules must also agree with each other. This preserves signature policy while preventing an additive operation from making APT unable to parse its source list.

Consequences

Adding a Pigsty repository also attempts to prepare its public-key file, including on offline hosts. Ordinary key failures no longer prevent repository setup. Falling back disables signature verification for those Pigsty definitions and is reported explicitly. A successful existence check preserves the administrator’s existing file; it does not validate that file’s contents. Third-party repository trust remains unchanged. APT may retain previously authenticated indexes with a warning when a key becomes unavailable. Successful repository configuration therefore does not prove that every index was freshly downloaded. The maintained repository reference describes the resulting defaults and paths.

Verification and evolution

The automatic-key implementation and repository regression tests are recorded in source commit 56f7353. Local regression tests exercise EL, Debian, and Ubuntu on both supported architectures, default and composite selections, existing-key reuse, denied existence checks, custom modules, unavailable repositories, implicit-key fallback, and explicit-key failure before repository mutation. Existing replacement tests continue to cover rollback.

Actual CLI tests on local EL9, EL10, Debian 12, and Ubuntu 24 ARM64 guests use isolated mount namespaces. They verify installation as an ordinary user through sudo with missing key directories, exact embedded bytes and permissions, repeated execution, composite selections, parseable structured output, implicit-key failure continuing with a warning, and explicit-key failure stopping before repository replacement. Real DNF/APT refreshes use isolated caches, and the resulting indexes are queried for available packages. APT tests also verify that the installed key is referenced without NO_PUBKEY warnings and that explicit signed-by with trusted=no authenticates the metadata. These checks do not install packages or verify RPM package signatures. The guests' original repository definitions, keys, and caches remain unchanged.

Follow-up regression checks cover retained APT sources and previously authenticated caches, custom-key absence before both add and replacement, a valid custom key with an unusable default path, and mixed explicit/implicit definitions. Permission tests deny ordinary-user traversal of the key directory and verify both privileged installation and rejection of a hidden symlink. RPM import tests use an isolated copy of the guest’s RPM database.

The trust refinement in a95f37f adds repeated boot/add and overlapping-module tests, retained .list and Deb822 .sources fixtures, explicit-conflict rejection before file changes, key-failure behavior, and replacement. Linux guest acceptance also exercises a real APT parser with isolated source and state directories, since fixture tests alone do not establish native APT compatibility.

Current status

Automatic key installation shipped in v1.9.0; APT release-level trust reconciliation is implemented in source commit a95f37f, without a release claim. See the current reference linked above for usage and platform requirements.