feat: package OpenShell for Fedora #3510

Note: This issue tracks findings and work items specific to the upstream
OpenShell project's own Fedora packaging posture — the repo's openshell.spec,
its build/license/bundling gaps, and decisions made at the project level.

Status (2026-10-12):

• Scope: no release-pipeline changes are planned for this work (scoping comment).
• Decided (via bug: openshell.spec %build does not compile OpenShell from source #4244, closed 2026-10-08): the Fedora-targeted spec is maintained separately from this repo's prebuilt-binary openshell.spec.
• Still open: where that spec lives. @olivercalder points out that official distro packaging needs build flags, dependencies and the Rust toolchain version kept in lockstep with the core repo. That argues for keeping it in this repo (with release-qualification CI possibly separate) and for reducing CI time directly instead of splitting repositories. The repo-structure RFC is expected to settle this (@SDAChess).
• Done so far: crate license aggregation (item 5, crate side), plus findings for item 2 (Fedora 44 grpcio and protobuf) and item 6 (Fedora's Z3 4.16 versus z3-sys).
• Independent of the location decision: the item 2 fix, item 5 (non-crate content), item 6 (feat: unbundle Z3 from gateway runtime packaging #1969), item 7, and item 10.
• Waiting on the location decision: items 1, 3, 8 and 9, and the Fedora package review request.

User Story

As a Red Hat engineer helping productize OpenShell for internal RPM/entitlement use, and as an OpenShell contributor, I want OpenShell available as a properly reviewed Fedora package, so Fedora users and downstream consumers can install it through their normal package manager instead of install scripts or third-party COPR repos.

Problem Statement

OpenShell has no path into Fedora today. The repo carries a root-level openshell.spec intended for Fedora/EPEL, and a .packit.yaml that already automates source/vendor tarball generation and version injection — but the spec itself isn't build-ready as checked in: %build consumes externally prebuilt binaries rather than compiling from source, which Koji/mock cannot support. Getting into Fedora also requires resolving vendored-dependency policy questions (~600 vendored Rust crates), a bundled library with a system equivalent (Z3), a vendored crypto stack that bypasses system crypto policy, and a Python SDK subpackage whose build-time proto tooling may not be compatible with what Fedora ships.

Impact / Why This Matters

Several Red Hat product efforts want a supported, source-buildable path to OpenShell RPMs; Fedora-first is one of two distribution paths being evaluated internally, and landing in Fedora is more durable and community-aligned than an internal-only channel. Today the only RPM path is a hand-rolled internal COPR build — not Fedora-reviewed, not broadly redistributable.

Proposed Design

Work through the concrete engineering items below roughly in the order listed, then proceed through Fedora's package review process once the spec is review-ready.

Architecture decision (2026-10-08): raised by @AndreLustosa: keep the current root openshell.spec (prebuilt-binary, fast for developer iteration) and add a separate Fedora-targeted spec (fully source-building, vendored) instead of converting the existing spec in place. The two-spec split is decided (see #4244). What remains open is where the Fedora spec lives, and which spec .packit.yaml's specfile_path should point to. Keeping packaging in this repo makes build flags, dependencies and toolchain versions easy to keep in sync; a separate repo in the org keeps core CI shorter but needs that synchronization maintained deliberately. To be settled in the repo-structure RFC.

Acceptance Criteria

• The Fedora-targeted spec (location per the repo-structure RFC) builds via rpmbuild/mock from source with no network access after %prep
• Vendored dependencies, plus non-crate content (docs, man pages, systemd unit, Python SDK files), are license-audited and correctly reflected in License:
• Z3 and vendored-crypto bundling concerns are resolved or explicitly documented
• A package review request is filed and approved via Fedora's New Package Process
• OpenShell builds successfully in Fedora Rawhide

Alternatives Considered

• Internal-only RPM distribution (via an internal COPR/entitlement channel) — already in progress in parallel by a separate internal team; faster to a shippable artifact but doesn't benefit the broader Fedora/community ecosystem and adds a second packaging surface to maintain long-term.
• Container-image-only distribution (status quo) — doesn't meet the needs of consumers who want a system-package-manager-installable binary.

Work Items

1. Fix %build to compile from source instead of consuming prebuilt binaries

Split out to #4244, closed 2026-10-08. The %build fix belongs in the Fedora-targeted spec, which is maintained separately from this repo's prebuilt-binary openshell.spec. Where that spec lives is still open (see Status).

User Story: As someone building OpenShell via rpmbuild/mock (Fedora's build path), I want %build to actually invoke cargo build, so the package can build in a network-isolated Fedora build environment.

Problem: %build only runs test -x "${OPENSHELL_PREBUILT_BINARIES_DIR}/openshell" (and equivalents for gateway/prover); %install copies binaries from that externally populated directory. No compilation happens inside the RPM build. Scope here depends on the two-spec decision above — this may mean fixing openshell.spec in place, or building a new Fedora-targeted spec from scratch using this as the reference for what's wrong.

Impact: Disqualifying for Fedora — Koji requires building from source inside its sandboxed, network-isolated root. The current external-CI workaround has no Fedora equivalent.

Acceptance Criteria:

• %build runs cargo build --release --offline --locked for openshell, openshell-gateway, openshell-prover against the %cargo_prep-vendored sources
• Builds successfully in a mock chroot with networking disabled
• No remaining dependency on OPENSHELL_PREBUILT_BINARIES_DIR or similar
• %global debug_package %{nil} is either resolved (debuginfo generated properly) or explicitly justified — this is a known Fedora review flag and reviewers will ask about it directly

2. Generate Python protobuf stubs during the build — and confirm Fedora's grpcio-tools can actually build them

User Story: As a Fedora packager building python3-openshell, I want the protobuf stubs generated as part of the build, so the package doesn't ship stale or missing files, and I want confidence that Fedora's own tooling can actually produce a working SDK.

Problem: python/openshell/_proto/*.py is .gitignored, produced by tasks/scripts/generate_python_proto.py. %install copies these files but nothing in %prep/%build generates them first. Separately, openshell.spec already carries a comment acknowledging Fedora ships older grpcio/protobuf than the SDK needs (grpcio 1.48 / protobuf 3.19 vs. the SDK's >=1.60 / >=4.25 requirement), currently worked around by using Recommends instead of Requires for the runtime dependency. That workaround doesn't address whether Fedora's python3-grpcio-tools can even generate correct stubs at build time.

Impact: Without proto generation in the build, the subpackage either fails to build cleanly from a clean checkout or silently packages stale stubs. Separately, if Fedora's grpcio-tools/protobuf versions are genuinely incompatible with what the generated stubs need at runtime, shipping python3-openshell via Fedora's system packages may not work at all regardless of how proto-gen is wired up.

Open question raised by @AndreLustosa, unresolved: either (a) drop the python3-openshell subpackage from the Fedora package entirely, or (b) vendor python3-grpcio-tools and python3-protobuf alongside the Rust dependency tree. Needs someone to actually test proto generation and the resulting SDK against Fedora's shipped grpcio/protobuf versions before choosing.

Findings (2026-10-08 comment): tested on Fedora 44 in a container with distro packages only. tasks/scripts/generate_python_proto.py fails because protoc 3.19 (grpcio-tools 1.48.4) has no --pyi_out. With that flag skipped, generation works and import openshell succeeds once googleapis-common-protos and httpx are installed (the spec did not list them). Keeping python3-openshell looks viable without vendoring grpcio-tools or protobuf. Not yet tested: a live gateway on grpcio 1.48, EPEL 10, Rawhide, or offline generation inside %build. A small fix (a --no-pyi option and the missing spec dependencies) is prepared and will be opened as a PR against this issue.

Acceptance Criteria:

• %prep/%build runs proto generation offline against vendored proto/*.proto, if the subpackage is kept
• Fedora's python3-grpcio-tools/python3-protobuf versions are tested against the SDK's actual requirements; decision made to drop the subpackage or vendor its Python build/runtime deps
• Builds successfully from a clean checkout
• %check verifies stub files exist and import correctly (if kept)

3. Harden and verify the existing .packit.yaml source/vendor generation — not a new script

Status: deferred with the packaging-location decision (repo-structure RFC).

User Story: As a packager maintaining openshell.spec across version bumps, I want confidence that source and vendor tarball generation is reproducible and correct, so every release can be re-packaged consistently and reviewed.

Correction: this is not greenfield work — .packit.yaml's create-archive action already does both halves: it builds openshell-${VERSION}.tar.gz via git ls-files+tar, and openshell-${VERSION}-vendor.tar.xz via cargo vendor --locked. Flagged by @AndreLustosa and confirmed by inspecting the file directly. The work here is verifying and hardening this existing mechanism, not writing a new script.

Impact: Fedora review requires packagers to explain and reproduce exactly how sources were generated — a standard reviewer question. The existing Packit actions answer that, but need to be verified as actually correct and actively exercised (see item 8 — evidence that these are running at all is currently missing).

Acceptance Criteria:

• Confirm create-archive's output matches what openshell.spec's Source0/Source1 expect, including the item-2 proto-stub question
• Confirm fix-spec-file's version/release injection (see item 4) is compatible with whatever %build fix lands in item 1
• Document the existing mechanism in the spec's header comment so it's not mistaken for missing again

4. Verify the version/Release scheme — largely already handled by .packit.yaml

User Story: As a Fedora packager, I want Version/Release to follow Fedora's guidelines, so the package can be tracked through normal Fedora update tooling.

Correction: the checked-in spec's stale %global openshell_version 0.0.37 and unusual git-describe-style Release are very likely just placeholders — .packit.yaml's fix-spec-file action already rewrites both %global openshell_version and Release (via OPENSHELL_RPM_RELEASE/PACKIT_RPMSPEC_RELEASE) as part of CI-driven builds. This needs verifying rather than assuming the checked-in values are the real bug.

Impact: If fix-spec-file is working correctly, this item is mostly about documentation and confirming the mechanism — not building new version-bump tooling. If it's not actually wired into a real build path (see item 8), this is still an open problem.

Acceptance Criteria:

• Confirm fix-spec-file actually produces a Fedora-conformant Version/Release in a real build
• Document the actual source of truth for Version/Release (Packit-injected vs. hand-maintained) so packagers don't get confused by the checked-in placeholder values
• If fix-spec-file isn't sufficient or isn't active, fall back to a manual %autorelease/%autochangelog approach

5. Aggregate all licenses — vendored crates and non-crate content — into an accurate SPDX License: tag

Crate side done (see earlier comment): minimal SPDX expression Apache-2.0 AND BSD-3-Clause AND CC0-1.0 AND CDLA-Permissive-2.0 AND ISC AND MIT AND Unicode-3.0 AND Zlib, applied to the root openshell.spec. Non-crate content (man pages, systemd unit, Python SDK source) still needs manual accounting.

User Story: As a packager and downstream RPM consumer, I want License: to accurately reflect every license shipped in the binary, so the package is legally accurate and passes Fedora licensing review.

Problem: openshell.spec sets License: Apache-2.0, but the binaries statically bundle ~600 vendored crates under mixed licenses (MIT, BSD variants, MPL-2.0, Unicode-3.0, ISC, etc.). %cargo_license/cargo_license_summary generate a report for crates, but nothing reconciles it into the spec's License: field. Separately (raised by @AndreLustosa): non-crate content — man pages, the systemd unit, docs, and the Python SDK's own source files — also needs explicit license accounting; the crate-license tooling doesn't cover any of it.

Impact: Fedora requires License: to be an SPDX expression covering every shipped license, not just the project's own. An inaccurate tag is a hard review blocker, and any license not on Fedora's allowed list needs a Fedora Legal conversation.

Proposed Design: Compute the aggregated SPDX expression from %cargo_license's output as part of item 3's tooling for the crate side; manually audit and document licenses for non-crate content separately, since there's no automated tooling for that half.

Acceptance Criteria:

• License: (per subpackage as needed) is a correct SPDX union of all shipped licenses, crate and non-crate
• Any non-allowed license is flagged for Fedora Legal review
• A repeatable process re-checks crate-license aggregation whenever Cargo.lock changes
• Non-crate content licenses are documented explicitly, not assumed to inherit the project's Apache-2.0

Alternatives Considered: One-time manual audit/hand-patch — rejected; will drift silently as dependencies change. Leave as Apache-2.0 — rejected; this is a licensing-accuracy problem independent of Fedora.

6. Link against the system Z3 (BuildRequires: z3-devel)

Resolved for the Fedora build (2026-10-14). #3275 made the installed system Z3 the default for ordinary Cargo builds (vendored-z3 is an opt-in, and release binaries use a static Z3 from Nix). In a fedora:44 container with z3-devel 4.16.0, cargo test -p openshell-prover --lib passes 105 of 105 with the precompiled z3-sys 0.13.0 bindings and with z3-sys's bindgen feature (which needs clang-devel and Z3_SYS_Z3_HEADER=/usr/include/z3/z3.h). Details are on #1969. The Fedora spec needs BuildRequires: z3-devel; #1969 covers the other package surfaces and is not a prerequisite for this item.

Acceptance Criteria:

• The Fedora spec builds with BuildRequires: z3-devel and no vendored Z3

7. Document the vendored-crypto (aws-lc-rs/rustls/ring) bundling justification

User Story: As a Fedora reviewer or security-conscious consumer, I want a documented justification for why OpenShell bundles its own TLS/crypto stack instead of system OpenSSL, so the decision is auditable.

Problem: The vendor tree includes aws-lc-rs, aws-lc-sys, ring, rustls (plus tokio-rustls, quinn) — a fully vendored crypto/TLS stack that bypasses update-crypto-policies. This is a known Fedora Rust-review flashpoint and is independently flagged internally as a FIPS blocker for a separate internal RPM effort.

Impact: Without a documented justification, this will likely draw direct reviewer pushback, and it's a shared blocker with the internal RHOAI/RHAIE effort — resolving it once here benefits both.

Confirmed sufficient as scoped by @AndreLustosa: FIPS compliance is the real underlying problem, but documenting it as a known, flagged gap (rather than attempting a fix in this effort) is an acceptable answer for now.

Proposed Design: Investigate whether an OpenSSL-backed feature flag is feasible without a large refactor; if not, write the formal bundling-exception rationale for Fedora review.

Acceptance Criteria:

• Written justification (spec comments and/or packaging doc) covering why the stack is vendored, whether that's expected to change, and current blockers
• Explicit coordination noted with the related internal FIPS/crypto-policy effort

Alternatives Considered: Switch to OpenSSL-backed TLS now — likely correct long-term but too large for this push; tracked as a documented gap instead. Say nothing, let a reviewer raise it — rejected; better to get ahead of a known blocker.

8. Verify whether .packit.yaml's existing copr_build jobs are actually active — then build/validate the spec

Status: deferred with the packaging-location decision (repo-structure RFC).

User Story: As a maintainer of openshell.spec, I want CI to actually build the package, so future changes don't silently break Fedora buildability again.

Correction: .packit.yaml already defines copr_build jobs targeting fedora-all and epel-10 on pull_request, commit, and release triggers — exactly this item's ask, at least on paper. Flagged by @AndreLustosa. However, this could not be confirmed as actually active: checking several recent PRs (including CI-focused ones) turned up zero Packit/Copr status checks of any kind. This suggests the Packit GitHub App may not be installed/enabled for this repo, or the jobs aren't reporting back — not that the config is wrong, but that it's unverified whether it runs at all today.

Impact: If genuinely active, this item may already be substantially solved and just needs confirmation + hardening. If not active, this is still fully open, and tasks/scripts/test-packaging-assets.sh's string-only assertions remain the only current check — which never invokes rpmbuild/mock.

Acceptance Criteria:

• Confirm with a maintainer/Andre/Robby whether the Packit GitHub App is actually installed and these copr_build jobs are live
• If active: verify they actually catch a real %build breakage (e.g. temporarily reintroduce a known failure and confirm the check fails)
• If not active: get it activated, or fall back to a mock-based GitHub Actions job as originally proposed
• Coordinated with ci(qualification): test DEB and RPM installation profiles #3454 rather than duplicating it

Alternatives Considered: Periodic manual builds — rejected; exactly the kind of check that rots without automation. Only catch breaks via Rawhide/COPR post-merge — rejected as too late.

9. Ship openshell-supervisor / openshell-sandbox as on-disk subpackages

OCI-image-sourced supervisor is sufficient functionally, but on-disk subpackages give parity with the RHEL9 spec.

Acceptance Criteria:

• Both binaries are built static-PIE (they are injected into arbitrary musl/glibc sandbox images, so static linking is functional, not stylistic) and the reason is recorded in the spec
• Subpackages carry Requires: openshell-gateway = %{version}-%{release} to prevent version drift

10. Honor PROTOC / system protoc in the Rust build

openshell-core, openshell-server (its storage proto) and openshell-sandbox-backend each have a build.rs that always uses protoc-bin-vendored's prebuilt protoc binary and bundled well-known includes, and ignores PROTOC. Each also re-runs itself with PROTOC_INCLUDE removed so the bundled include tree wins. This is separate from item 2's Python stub generation.

A system protoc looks sufficient: every proto in the repo is plain proto3 and imports only google/protobuf/{descriptor,duration,struct,timestamp}.proto. All of them (the public protos, the server storage proto, and the sandbox-backend proto) compile with Fedora 44's protobuf-compiler 3.19.6 and the well-known includes from protobuf-devel. A full cargo build with a system protoc has not been verified yet.

Acceptance Criteria:

• All three build scripts use an already-set PROTOC (and PROTOC_INCLUDE when set), or the system protoc, when present; behavior is unchanged when PROTOC is unset
• Verified with a system protoc on Fedora
• Open follow-up, only if Fedora review needs it: the protoc-bin-vendored* crates ship prebuilt protoc binaries in the vendored source tree. A default-on cargo feature could let distro builds drop them from the dependency graph entirely (not verified whether this is required)

Related: #1969, #2204, #3454. Duplicates #3509 and #3511 (both closed) — this issue (#3510) is the canonical one going forward.

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request