Overview

Relevant source files

• .github/CODEOWNERS
• LICENSE
• README.md
• cosign.pub

This document provides an introduction to the ublue-os/packages repository, which serves as the central RPM package management system for Universal Blue projects. The repository maintains RPM specifications, orchestrates automated builds through containerized infrastructure, and distributes packages via COPR repositories to various Universal Blue distributions including Bluefin, Aurora, and Bazzite.

This overview covers the high-level architecture, repository organization, and package lifecycle. For details on specific subsystems, see:

• Repository structure and directory organization: Repository Structure and Organization
• Contribution workflow and versioning: Contributing and Package Lifecycle
• COPR distribution mechanisms: COPR Distribution Strategy
• Build system details: Build System and CI/CD

Sources: README.md1-90

---

Purpose and Scope

The ublue-os/packages repository fulfills three primary functions:

1. Package Source Management: Maintains .spec files and patches for RPM packages specific to Universal Blue distributions
2. Build Infrastructure: Provides containerized build environments (ublue-builder) with mock-wrapper orchestration
3. Distribution Pipeline: Automates package building and distribution through multiple COPR repositories

The repository produces packages that are consumed by rpm-ostree-based Universal Blue images, extending the base Fedora/CentOS ecosystem with Universal Blue-specific functionality and hardware support.

Sources: README.md1-8

---

High-Level Architecture

System Overview

Sources: README.md1-90 Diagram 1 from high-level architecture

---

Repository Structure

The repository is organized into four primary directories:

Directory	Purpose	Examples
akmods/	Kernel module packages with automatic kmod building	xone-kmod, scx-scheds
packages/	Universal Blue-specific packages	ublue-os-just, ublue-bling, ublue-brew
staging/	Temporary patches for upstream packages	gnome-shell, mutter, bazaar, flatpak
ublue-builder/	Build container definition and tooling	Containerfile, entrypoint.sh

Additional top-level directories include distribution-specific packages (bazzite/, bluefin/, ucore/) and configuration files for automation (.github/, Justfile).

Sources: README.md1-90 .github/CODEOWNERS1-18

---

Package Lifecycle

Build and Distribution Flow

The package lifecycle follows this workflow:

1. Source Changes: Developers modify spec files or Renovate creates automated update PRs
2. Security Gate: PRs require manual safe-to-run label from maintainers to prevent malicious code execution README.md77-82
3. Build Execution: GitHub Actions triggers ublue-builder container which uses mock-wrapper to orchestrate builds
4. Validation: rpmlint and spec format checks ensure package quality
5. Distribution: Packages are manually added to COPR (one-time), then COPR automatically rebuilds on repository changes README.md36-37
6. Consumption: Universal Blue OS images fetch packages via rpm-ostree during image builds

Sources: README.md27-86 Diagram 4 from high-level architecture

---

Key Components

Build Infrastructure

Component	Location	Function
ublue-builder	ublue-builder/	Container image with mock, rpkg, rpmlint, spectool
mock-wrapper	ublue-builder/entrypoint.sh	Orchestrates spec processing, source fetching, and mock builds
Justfile	Justfile	Developer CLI with just build, just overlay commands
GitHub Actions	.github/workflows/build-package.yml .github/workflows/builder.yml	CI/CD pipeline for automated builds and container image creation

For detailed documentation on build system components, see Build System and CI/CD.

Automation Layer

Component	Location	Function
Renovate	.github/renovate.json5	Automated dependency updates with custom regex managers for spec files
safe-to-run label	GitHub PR labels	Security gate preventing untrusted code execution README.md79-82
rpmlint	Run via mock-wrapper	Package quality validation enforcing Fedora guidelines README.md32

Renovate uses custom macros to parse version strings from spec files and creates automated PRs when upstream versions change. See Dependency Management with Renovate for details.

Distribution Channels

The repository feeds multiple COPR repositories, each with distinct purposes:

• ublue-os/main: Stable packages for production images
• ublue-os/staging: Packages with upstream patches pending merge
• ublue-os/akmods: Signed kernel modules for hardware support
• Additional COPRs: Distribution-specific packages (bazzite, bluefin, ucore)

Once packages are manually added to a COPR (a one-time operation), COPR automatically rebuilds them when the GitHub repository is updated. See COPR Distribution Strategy for details.

Sources: README.md7-8 README.md36-37

---

Package Categories

Core System Packages

Packages are categorized by functionality:

• User Tools: CLI and shell enhancements (ublue-os-just, ublue-bling, ublue-brew) - see User Tools and CLI Enhancements
• System Services: Background services for automount, setup, updates - see System Services and Integration
• Desktop Integration: Software centers and patched desktop components - see Desktop Integration
• Hardware Support: Kernel modules with automatic signing - see Hardware Support and Kernel Modules

Sources: .github/CODEOWNERS1-18 Diagram 3 from high-level architecture

---

Development Workflow

Local Package Building

Developers can build packages locally using the just build command, which launches the same ublue-builder container used in CI:

The just build command mounts the mock/ directory locally, allowing inspection of build logs, chroots, and resulting RPMs/SRPMs README.md10-25

For detailed local development documentation, see Local Development with Just.

Version Bumping Strategy

When updating packages, the appropriate field must be incremented:

Scenario	Field to Bump	Tool	Example
Upstream version update	Version:	Manual edit	Version: 1.2.3 → Version: 1.2.4
Packaging changes only	Release:	rpmdev-bumpspec	Release: 1%{?dist} → Release: 2%{?dist}
Version bump	Release:	Reset	Release: 5%{?dist} → Release: 1%{?dist}

The rpmdev-bumpspec command automatically updates the Release field and adds a changelog entry README.md41-75

Sources: README.md13-25 README.md41-75

---

Security and Quality Assurance

Security Model

All pull requests undergo a security review before CI execution:

1. Maintainers review PR for RCE exploits or GitHub Actions abuse
2. Maintainer applies safe-to-run label to approve PR
3. GitHub Actions proceeds with build README.md77-82

This prevents malicious code execution in the CI environment while allowing automated dependency updates from trusted sources like Renovate.

Quality Requirements

All packages must meet these criteria:

• Pass rpmlint: All packages must pass rpmlint validation (except rpkg-based packages)
• Fedora Guidelines: Follow Fedora Packaging Guidelines with case-by-case exceptions
• Offline Buildable: Packages must build offline after sources are fetched (required for GitHub Actions/mock)
• Renovate Compatible: Packages must be automatically updatable by Renovate with appropriate version detection macros

For contribution workflow details, see Contributing and Package Lifecycle.

Sources: README.md27-44 README.md77-82

---

Multi-Architecture Support

The repository supports both x86_64 (amd64) and aarch64 (arm64) architectures:

GitHub Actions builds packages on native runners for each architecture, producing architecture-specific RPMs. The ublue-builder container image itself is built as a multi-platform manifest supporting both architectures.

For details on multi-architecture builds, see Multi-Architecture Build Support.

Sources: README.md23-24 Diagram 2 from high-level architecture

---

Testing and Validation

Local Testing Environment

Developers can create an identical testing environment to CI:

This ensures packages build correctly before submitting PRs README.md84-85

Automated Testing

The repository includes automated validation:

• Renovate Configuration Tests: Validate .github/renovate.json5 syntax and regex managers
• Spec Lint Tests: Ensure spec files follow formatting conventions
• Integration Tests: Verify packages install correctly in target distributions

For automation pipeline details, see GitHub Actions CI/CD Pipeline.

Sources: README.md84-86 Diagram 4 from high-level architecture

---

Relationship to Universal Blue Distributions

The packages repository serves as the foundation for multiple Universal Blue distributions:

Distribution	Primary COPRs Used	Notable Packages
Bluefin	ublue-os/main	ublue-os-just, ublue-bling, bazaar, gnome-shell
Aurora	ublue-os/main, ublue-os/staging	Same as Bluefin + staging packages
Bazzite	ublue-os/main, ublue-os/akmods	Gaming packages + xone-kmod, scx-scheds
uCore	ublue-os/main	Server-focused packages

Each distribution selects which COPR repositories to enable, allowing staging of experimental features in Aurora before promotion to Bluefin's stable channel.

Sources: README.md5-8 .github/CODEOWNERS1-18 Diagram 1 from high-level architecture

---

Repository Licensing

The repository is licensed under Apache License 2.0, allowing free use, modification, and distribution with proper attribution.

Sources: LICENSE1-202 cosign.pub1-5