Metadata-Version: 2.1
Name: gentoo-build-publisher
Version: 3.0.0
Summary: Gentoo Build Publisher
Author-Email: Albert Hopkins <marduk@letterboxes.org>
License: GPL3+
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Operating System Kernels :: Linux
Classifier: Topic :: System :: Operating System
Classifier: Topic :: System :: Software Distribution
Classifier: Topic :: System :: Systems Administration
Project-URL: homepage, https://github.com/enku/gentoo-build-publisher
Project-URL: repository, https://github.com/enku/gentoo-build-publisher
Requires-Python: >=3.11
Requires-Dist: ariadne>=0.14.0
Requires-Dist: ariadne_django
Requires-Dist: celery[msgpack]
Requires-Dist: django
Requires-Dist: requests
Requires-Dist: yarl!=1.9.1
Requires-Dist: gbpcli>=3.0.0
Requires-Dist: orjson>=3.9.1
Requires-Dist: cryptography>=42.0.4
Requires-Dist: rich>=13.7.0
Requires-Dist: blinker>=1.9.0
Provides-Extra: redis
Requires-Dist: rq>=1.15.1; extra == "redis"
Provides-Extra: test
Requires-Dist: factory-boy>=3.3.3; extra == "test"
Requires-Dist: unittest-fixtures>=2.3.0; extra == "test"
Description-Content-Type: text/markdown

<p align="center">
<img src="https://raw.githubusercontent.com/enku/screenshots/master/gentoo-build-publisher/dashboard.png" alt="Gentoo Build Publisher dashboard" width="100%">
</p>

# Gentoo Build Publisher

## Introduction

Gentoo Build Publisher (GBP) is a Gentoo build server, binary package host
(binhost), ebuild repo server, and configuration manager in one which uses
[continuous integration](https://en.wikipedia.org/wiki/Continuous_integration)
and other tools to deliver successful, consistent "builds" for a single
machine or multiple heterogeneous Gentoo machines.

In case you didn't know, [Gentoo Linux](https://www.gentoo.org/) is a
source-based rolling-release meta-distribution that you can twist and mold
into pretty much anything you like. That's just a verbose way of saying Gentoo
is awesome.

If you run a Gentoo system, say a laptop, you may be updating your system
using the standard `emerge --sync` followed by a world update. This pulls in
the latest ebuilds from the Gentoo repo and if there are any updates
applicable to your system then they get built on your system.

Except sometimes they don't.

Sometimes builds fail. Sometimes `USE` flags need to be changed. Sometimes
there's an update to a piece of software that is buggy and you want to revert.
Sometimes a build takes a long time and you don't want to wait.

Well since Gentoo is the distribution you build yourself, CI/CD seems like a
natural fit. Enter Gentoo Build Publisher.

Gentoo Build Publisher combines a repo/overlay server, basic configuration
management, and binary package server (binhost) for complete and atomic
builds.  Successful builds performed by Jenkins are served by GBP where client
machines sync from.


## Procedure

* Build a Gentoo Build Publisher instance. Refer to the [Install
  Guide](https://github.com/enku/gentoo-build-publisher/blob/master/docs/how-to-install.md).
* Create "machines" and "repos" jobs in Jenkins.  For example `gbp addrepo
  gentoo https://anongit.gentoo.org/git/repo/gentoo.git; gbp addmachine base
  https://github.com/enku/gbp-machines.git` Use [the gbp-machines
  repo](https://github.com/enku/gbp-machines) as a starting point. This can
  also be done manually within the Jenkins UI.
* Once a Jenkins job has been pulled by Gentoo Build Publisher it can be
  published so that actual machines can use it (e.g. rsync for repos, http for
  binpkgs).  Use the CLI (`gbp publish`) to publish a pulled build.
* If the job fails, it will not be pulled.
* Your real machine, for example, `base`, syncs from, `rsync://gbp/repos/base/gentoo`.
  You can dynamically acquire the `repos.conf` file from
  `https://gbp/machines/base/repos.conf` and the `binrepos.conf` from
  `https://gbp/machines/base/binrepos.conf`.

<p align="center">
<img src="https://raw.githubusercontent.com/enku/screenshots/refs/heads/master/gentoo-build-publisher/gbp.svg" alt="Jenkins build" width="90%">
</p>

# CLI

The [command-line interface](https://github.com/enku/gbpcli#readme) can
inspect, publish, pull, schedule builds and more.

<p align="center">
<img src="https://raw.githubusercontent.com/enku/screenshots/refs/heads/master/gbp-ps/screenshot.gif" alt="gbpcli screenshot" width="100%">
</p>

# Plugins

Various plugins exist for Gentoo Build Publisher. Some are "server" plugins,
meaning they plug into Gentoo Build Publisher, the server. Others are "client"
plugins, meaning they plug into the CLI. And some are both.  The following
Plugins are available.

| Plugin | Description | Client/Server |
| ------ | ----------- | ------------- |
| [archive](https://github.com/enku/gbp-archive) | A plugin to dump and restore builds | Both (but only runs on from the server) |
| [feeds](https://github.com/enku/gbp-feeds) | Atom/RSS feeds for Gentoo Build Publisher | Server |
| [fl](https://github.com/enku/gbp-fl) | A [pfl](https://www.portagefilelist.de/)-inspired plugin | Both |
| [notifications](https://github.com/enku/gbp-notifications) | A plugin that can send notifications when events occur | Server |
| [ps](https://github.com/enku/gbp-ps) | A plugin to display your Gentoo Build Publisher processes | Both |
| [purge](https://github.com/enku/gbp-purge) | A plugin to purge old builds | Server |
| [webhook](https://github.com/enku/gbp-webhook) | A webhook for gbp-notifications to display desktop notifications and more | Client |

# Articles

Below are some articles that explain some aspects of Build Publisher in
detail.

- [Introducing Gentoo Build Publisher](https://lunarcowboy.com/introducing-gentoo-build-publisher.html): June 2021
- [Exploring the Gentoo Build Publisher Dashboard](https://lunarcowboy.com/exploring-the-gentoo-build-publisher-dashboard.html): November 2021
- [Getting failure logs](https://lunarcowboy.com/gentoo-build-publisher-getting-failure-logs.html): April 2022
- [Installing Gentoo Build Publisher](https://lunarcowboy.com/installing-gentoo-build-publisher.html) August 2022
- [Rolling Back a Rolling Release with Gentoo Build Publisher](https://lunarcowboy.com/rolling-back-a-rolling-release-with-gentoo-build-publisher.html): September 2022
- [Bisecting GBP Builds to Find a Bad Package](https://lunarcowboy.com/bisecting-gbp-builds-to-find-a-bad-package.html): April 2023
- [Gentoo Build Publisher: Pro-Tip: Purging a Machine that is Disabled on Jenkins](https://lunarcowboy.com/gentoo-build-publisher-pro-tip-purging-a-machine-that-is-disabled-on-jenkins.html): August 2023
- [Gentoo binary host, Gentoo Build Publisher version 2 & Plugins](https://lunarcowboy.com/gentoo-binary-host-gentoo-build-publisher-version-2-plugins.html): January 2024
- [Running arbitrary commands in a machine's chroot](https://lunarcowboy.com/gentoo-build-publisher-running-arbitrary-commands-in-a-machines-chroot.html): February 2024
- [Gentoo Build Publisher: Manually Running Repo
  Jobs](https://lunarcowboy.com/gentoo-build-publisher-manually-running-repo-jobs.html):
  September 2024
- [Gentoo Build Publisher: Using Separate Machines for
  Overlays](https://lunarcowboy.com/gentoo-build-publisher-using-separate-machines-for-overlays.html)
  September 2024
- [Announce: gbp-fl](https://lunarcowboy.com/announce-gbp-fl.html): February
  2025
- [Gentoo Build Publisher: dump &
  restore](https://lunarcowboy.com/gentoo-build-publisher-dump-restore.html):
  February 2025
- [Gentoo Build Publisher: Auth & API
  Keys](https://lunarcowboy.com/gentoo-build-publisher-auth-api-keys.html):
  April 2025
