Documentation · Gentoo tooling

Gentoo Overlay Publisher

A reusable ebuild construction and overlay reconciliation library, plus a GitHub Action for proposing safe Gentoo overlay updates.

Project status: Design and foundation. The library, executable and Action are not yet released. This documentation is an intentionally lightweight starting point.

Three interfaces, one engine

Go library

Construct ebuilds with a typed IR, update metadata and Manifests, and produce inspectable change plans. No G2 or build-tool imports in the core.

GitHub Action

Primary workflow integration: discover assets, calculate fresh changes automatically and open a reviewable overlay pull request.

CLI

Scriptable and local use of the same engine. Default publish, optional read-only plan, and local-only apply.

Intended source inputs

Release assets and metadata may come from GitHub Releases, a restricted GoReleaser metadata adapter, local generated package trees or a dedicated typed manifest. Users should not be forced to write a custom candidate YAML just to publish a conventional release.

Safety and verification

Publishing must reconcile a freshly read target state and produce a branch and pull request rather than committing directly to the default branch. Verification may independently use G2 and Portage; secret-bearing publication tests must run only from trusted workflows.

Coming documentation

Once implemented and verified, this site will grow to include Action inputs and outputs, CLI examples, Go package API references, candidate-source formats, PR strategies and Gentoo end-to-end integration guides. Until then, examples here describe design intent, not a runnable released interface.