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.

Key management and signing procedures are defined in:

:doc:`signing-keys` and :doc:`../security/identity/gpg-ssh-keys`


Release Flow
------------

The following diagram illustrates the high-level release flow.

.. mermaid::
   :align: center
   :caption: Shyft release flow
   :config: {"themeVariables": {"fontSize": "15px"}, "flowchart": {"nodeSpacing": 20, "rankSpacing": 30}}

   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

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:

:doc:`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:

:doc:`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.

.. mermaid::
   :align: center
   :caption: Trust boundary
   :config: {"themeVariables": {"fontSize": "15px"}, "flowchart": {"nodeSpacing": 20, "rankSpacing": 30}}

    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

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:

:doc:`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

Variables
---------

Adjust these variables to match the local environment:

.. code-block:: bash

   tag=35.0.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

Prepare trusted workspace
-------------------------

Clone the repository and check out the signed release tag:

.. code-block:: bash

   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:

.. code-block:: bash

   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 both distributions:

.. code-block:: bash

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

The resulting release tree is located at:

.. code-block:: text

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

Set release output path
-----------------------

For convenience, define:

.. code-block:: bash

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

Sign release artifacts
----------------------

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

.. code-block:: bash

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

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

Create repositories for publication
-----------------------------------

Create repository metadata for the selected channel:

.. code-block:: bash

   "$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

Copy signed repositories to publishing host
-------------------------------------------

Copy only the generated signed repositories to the publishing server:

.. code-block:: bash

   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.