Release Process

The Shyft release process establishes a verifiable chain of trust from maintainer identity and signed source code to published release artifacts.

Releases are built from signed source tags using controlled and reproducible build environments, and are finalized through hardware-backed cryptographic signing.

The process deliberately separates:

• Source verification

• Controlled artifact production

• Trusted signing and release publication

Only artifacts that have been produced through this process and explicitly signed are considered official Shyft releases.

The release process is reusable by downstream organisations because the trust root (the signing key) is configurable. Organisations may use their own hardware-backed signing keys and establish independent release identities while following the same release procedure.

Key management and signing procedures are defined in:

Signing Keys and GPG and SSH Key Management

Release Flow

The following diagram illustrates the high-level release flow.

        ---
config:
  flowchart:
    nodeSpacing: 20
    rankSpacing: 30
  themeVariables:
    fontSize: 15px

---
flowchart TD
    A["Git repository<br/>Signed commits and tags"]
    B["Controlled build environment<br/>Reproducible build"]
    C["Unsigned release artifacts"]
    D["Trusted signing host<br/>Nitrokey hardware key"]
    E["Signed release packages<br/>+ PROVENANCE.txt"]
    F["Users / operators<br/>Verify and install"]

    A -->|"checkout + verify"| B
    B -->|"build artifacts"| C
    C -->|"verify + approve"| D
    D -->|"sign + provenance"| E
    E -->|"publish"| F
    

Shyft release flow

Source Repository

Releases originate from signed Git tags in the Shyft repository.

Repository protections ensure:

• signed commits

• signed tags

• protected release branches

• verification of signed tags before build

These mechanisms establish a trusted starting point for the build process and link the release to a verifiable maintainer identity.

Build Stage

Release artifacts are produced in a controlled build environment using a clean checkout of a signed source tag.

The build process is executed using a minimal and version-controlled build image to ensure reproducibility and isolation.

Key properties of the build stage:

• Build is performed from a verified source revision

• Build environment is defined by a version-controlled image

• Build image is immutable and not modified during execution

• Build execution may be performed with network access disabled

• All build inputs are prepared and verified prior to execution

The output of this stage is a set of unsigned release artifacts together with the build metadata needed to assemble the release provenance record.

These artifacts are not trusted until they have been verified and signed.

Provenance Content and Role

Each official Shyft release includes a PROVENANCE.txt file describing the source revision, build environment, generated artifacts, and signing event associated with the release.

The provenance document is intended to complement, not replace, the native verification mechanisms provided by package managers such as RPM/dnf and pacman.

The provenance document is assembled and finalized within the trusted release environment and is not constructed from externally transported artifacts.

Package managers remain responsible for package signature verification, repository trust configuration, dependency handling, and installation. The provenance document adds release-level traceability by describing how the published artifacts were produced and approved.

Verification of the provenance document is described in:

Package Verification

Role of the Provenance Document

The provenance document provides a human-readable and signed record of the release process. Its purpose is to make it possible to:

• identify the exact source revision used for the release

• describe the controlled build procedure and build environment

• list the generated release artifacts and their cryptographic digests

• record the signing event that approved the release

• link repository snapshots and published artifacts back to the verified source and build procedure

This allows users, operators, and auditors to independently inspect the relationship between source code, build inputs, published artifacts, and release approval.

Relationship to Package Managers

The provenance document is a release-level record. It is not a replacement for native package metadata or repository metadata.

In particular, PROVENANCE.txt does not replace:

• RPM or pacman package signatures

• repository metadata such as repodata or pacman database files

• dependency metadata

• package installation and trust configuration handled by the operating system

Instead, the provenance document provides additional context that package managers do not normally describe in a single place, such as source revision, build image identity, release artifact set, and signing context.

Repository-Level Distribution

For repository-style distribution, the provenance document is published at the repository root together with its detached signature and the public release key.

A repository snapshot may therefore contain files such as:

PROVENANCE.txt
PROVENANCE.txt.asc
shyft-release-key.asc
index.html

alongside the native repository metadata and package files.

In this model, the provenance document describes the repository snapshot as a whole, including the package files and relevant repository metadata generated for that release.

Typical Provenance Content

The provenance document may include information such as:

• source repository URL

• source tag and commit hash

• source verification status

• build script or procedure identifier

• build image identity and digest

• references to build-environment manifests or SBOM files

• list of produced package artifacts

• cryptographic digests of artifacts

• repository metadata files and digests

• signing key fingerprint

• signing timestamp

The exact concrete format is generated by the release tooling in tools/release and is version-controlled together with the release procedure.

Accordingly, the documentation describes the intended structure and meaning of the provenance data, while the authoritative emitted format is the one produced by the corresponding release scripts.

Generation During the Release Process

The provenance information is assembled as part of the release process.

During the build stage, the release procedure gathers the source identity, build environment details, and the list of generated artifacts.

During the signing stage, the provenance document is finalized with release approval information, cryptographic digests, and signing metadata, and is then itself signed.

This ensures that the provenance document records both:

• how the artifacts were produced

• how the release was approved

Build Image

Build environments use a minimal build image designed only to produce packages.

The build image is treated as an immutable input to the release process and must not be modified during the build execution.

Characteristics:

• Minimal set of build tools and dependencies

• No unnecessary development tooling

• Version-controlled build recipe

• Rebuilt explicitly when dependencies change

Base images must be:

• Referenced by sha256 digest (never tags)

• Manually reviewed and approved before use

• Verified (e.g., cosign for Arch, inspection for Fedora)

Example:

FROM registry.fedoraproject.org/fedora-minimal@sha256:<approved-digest>

The selected digest is pinned in version control.

Signing Stage

Official releases are produced through a controlled signing procedure executed within the trusted release environment.

The signing process is performed on the same controlled infrastructure that produced the build artifacts, avoiding the need to transfer unsigned artifacts across external networks.

The signing process performs:

1. Final verification of build artifacts and build metadata

2. Completion of the provenance document with artifact digests and build details

3. Signing of packages using the Shyft release key

4. Verification of package signatures

5. Signing of the provenance document

6. Preparation of repository metadata and release publication

Private keys are stored on hardware devices (Nitrokey) and never leave the device.

Signing is performed using the Shyft release signing key as described in:

Signing Keys

Trust Boundary

The trusted domain includes both the build environment and the signing infrastructure. Unsigned artifacts are not transferred outside this domain.

Only signed release artifacts are published to external distribution channels.

        ---
config:
  flowchart:
    nodeSpacing: 20
    rankSpacing: 30
  themeVariables:
    fontSize: 15px

---
 flowchart TB
     subgraph TRUSTED["Trusted domain"]
         A["Signed source"]
         B["Controlled build"]
         C["Unsigned artifacts"]
         D["Signing host<br/>Nitrokey"]
         E["Signed release"]
         A --> B --> C --> D --> E
     end

     F["Users / operators"]

     E -->|"verify"| F
    

Trust boundary

Only signed artifacts from the trusted environment are official releases.

Trust Chain

The release process establishes the following verifiable chain:

Maintainer identity
    ↓
Signed Git commits and tags
    ↓
Verified source snapshot
    ↓
Controlled build environment
    ↓
Verified build artifacts
    ↓
Hardware-backed signing (Nitrokey)
    ↓
Signed release artifacts and provenance
    ↓
User verification and installation

Each stage in this chain can be independently verified.

Security Properties

The release process provides:

• protection against artifact tampering

• traceability from source to release

• cryptographic authenticity

• support for distributed, reproducible builds

• transparent and auditable procedure

• minimized reliance on external infrastructure

A local build may produce a candidate artifact, but only verified and approved signed artifacts are considered official releases.

User verification procedures are described in:

Package Verification

Release Runbook

This section provides a brief operator runbook for producing a Shyft release. It is intended as a practical companion to the full release-process documentation.

This runbook assumes:

• the release tag has already been created and pushed by an authorized maintainer

• build and signing are performed on the same trusted host

• only signed artifacts are copied to the publishing environment

• a hardware-backed OpenPGP token (Nitrokey used in this example)

Variables

Adjust these variables to match the local environment:

tag=35.2.1-1.1
workspace=$HOME/work/release-$tag
repo_url=https://gitlab.com/shyft-os/shyft
repo_dir=$workspace/shyft
tools_dir=$repo_dir/tools/release
buildah_dir=$repo_dir/tools/buildah

The release scripts default to the Shyft public signing key distributed with the source tree.

During signing, the scripts use the configured public key to identify the corresponding secret key available through GnuPG. If the secret key is stored on a hardware-backed OpenPGP token, GnuPG automatically uses the attached token to perform the signing operation.

Downstream organisations may override this by supplying their own public signing key. This allows the same release procedure to be reused while maintaining independent trust roots and signing identities.

The release scripts honor the PUBLIC_KEY_FILE environment variable. If unset, the default Shyft signing key is used.

PUBLIC_KEY_FILE="$HOME/keys/company-signing-key.asc"

Prepare trusted workspace

Clone the repository and check out the signed release tag:

mkdir -p "$workspace"
cd "$workspace"
git clone "$repo_url" shyft
cd "$repo_dir"
git checkout "$tag"

Optional: verify the signed tag according to the release-process documentation before proceeding.

Build trusted images

Build the local trusted build images:

cd "$workspace"
buildah unshare "$buildah_dir/build.sh" archlinux "$tag"
buildah unshare "$buildah_dir/build.sh" fedora "$tag"

Build unsigned release artifacts

Build the release artifacts for distributions:

cd "$workspace"
"$tools_dir/build-release.sh" archlinux "$tag" "$tag"
"$tools_dir/build-release.sh" fedora "$tag" "$tag"
"$tools_dir/build-release.sh" fedora44 "$tag" "$tag"

The resulting release tree is located at:

$workspace/shyft-build/$tag/release/

Set release output path

For convenience, define:

release_dir=$workspace/shyft-build/$tag/release

Sign release artifacts

Sign the packages and bind them to the generated provenance manifests:

"$tools_dir/sign-pacman.sh" \
  --manifest "$release_dir/archlinux/provenance/PROVENANCE.txt" \
  "$release_dir/archlinux/packages/"*.zst

"$tools_dir/sign-pacman.sh" \
  --manifest "$release_dir/msys2/provenance/PROVENANCE.txt" \
  "$release_dir/msys2/packages/"*.zst

"$tools_dir/sign-rpm.sh" \
  --manifest "$release_dir/fedora/provenance/PROVENANCE.txt" \
  "$release_dir/fedora/packages/"*.rpm

"$tools_dir/sign-rpm.sh" \
  --manifest "$release_dir/fedora44/provenance/PROVENANCE.txt" \
  "$release_dir/fedora44/packages/"*.rpm

Create repositories for publication

Create repository metadata for the selected channel:

"$tools_dir/create-archlinux-repo.sh" \
  --source "$release_dir/archlinux" \
  --channel stable \
  --public-repo-baseurl https://archlinux.helset.gotdns.org

"$tools_dir/create-fedora-repo.sh" \
  --source "$release_dir/fedora" \
  --channel stable \
  --public-repo-baseurl https://fedora.helset.gotdns.org

"$tools_dir/create-fedora-repo.sh" \
  --source "$release_dir/fedora44" \
  --channel stable \
  --public-repo-baseurl https://fedora44.helset.gotdns.org

"$tools_dir/create-msys2-repo.sh" \
     --source "$release_dir/msys2" \
     --channel stable \
     --public-repo-baseurl https://msys2.helset.gotdns.org

Copy signed repositories to publishing host

Copy only the generated signed repositories to the publishing server:

cd "$workspace"
scp -rp archlinux/stable/ pkg-publish:/srv/packages/archlinux
scp -rp fedora/stable/ pkg-publish:/srv/packages/fedora

Result

After these steps:

• release artifacts are built on the trusted host

• packages are signed on the trusted host

• repository metadata is generated

• only signed repositories are copied to the publishing environment

For policy, trust assumptions, role separation, and verification guidance, see the main release-process documentation.