The Problem

Omarchy ships software to users through a custom package repository that must support multiple release channels (edge → rc → stable) and architectures (x86_64, aarch64). Maintaining a large set of Arch PKGBUILD recipes, keeping them up‑to‑date, and publishing artifacts requires a repeatable build pipeline, automated upstream discovery, and a clean way to add new packages without secrets.

What This Does

The repo stores one recipe per package in pkgbuilds/<name>/.

  • PKGBUILD contains the Arch packaging logic.
  • .omarchy/package.json declares metadata and an upstream.watch block that drives automatic updates.

Scripts in bin/ orchestrate the lifecycle:

  • bin/add-package scaffolds a new recipe or imports an existing AUR recipe.
  • bin/build runs a containerized build (see build/Dockerfile) and produces unsigned packages in build-output/<channel>/<arch>/.
  • bin/publish-artifact uploads artifacts to the remote channel.

Helper scripts under helpers/ provide common logic (e.g., package-metadata.sh parses .omarchy/package.json, docker-helpers.sh handles image pulls).

CI is driven by GitLab CI files in each package directory (pkgbuilds/<name>/.gitlab-ci.yml) and a shared Docker image build pipeline (.github/workflows/builder-images.yml). The workflow checks source pinning (tests/pinned-sources.sh) and ensures checksum validity (updpkgsums).

How It Is Wired

Entry point: bin/build.

  1. bin/build parses arguments and loads the target package directory.
  2. It calls helpers/package-metadata.sh to read .omarchy/package.json, extracting upstream.watch and arch arrays.
  3. helpers/docker-helpers.sh builds or pulls the build image defined in build/Dockerfile.
  4. Inside the container, pacman -Syu --noconfirm installs build dependencies, then makepkg -si executes the PKGBUILD.
  5. The resulting .pkg.tar.zst files are copied out to build-output/<channel>/<arch>/.

The only external side effect is writing these artifacts; no database or network state is modified by the build itself. The CI pipeline (pkgbuilds/<name>/.gitlab-ci.yml) invokes the same bin/build script, captures logs, and uploads artifacts to the repository via bin/publish-artifact. These scripts are the single points of failure: any change in helpers/package-metadata.sh or helpers/docker-helpers.sh propagates to every package build.

How To Use It

Setup

git clone https://github.com/moses-y/omarchy-pkgs
cd omarchy-pkgs
# Ensure Docker or Podman is installed and the current user can run it

Add a package

bin/add-package my-package --source aur   # import an existing AUR recipe
# or
bin/add-package my-package --local --scaffold

Build locally

bin/build --package my-package            # builds for x86_64
bin/build --package my-package --arch aarch64

Publish

bin/publish-artifact build-output/edge/x86_64/my-package-1.0.0-1-x86_64.pkg.tar.zst

Configuration Edit pkgbuilds/my-package/.omarchy/package.json to set upstream.watch. The CI jobs run automatically on push to master; no additional secrets are required.

Real‑World Use

A developer updates PKGBUILD for 1password-cli, commits, and pushes to master. The GitLab CI job in pkgbuilds/1password-cli/.gitlab-ci.yml runs bin/build, generates a new package, and bin/publish-artifact uploads it to the edge channel. Users then install the package with pacman -U https://pkgs.omarchy.org/edge/x86_64/1password-cli-2.0.0-1-x86_64.pkg.tar.zst.

Code Health & Issues

  • Low (Dependencies without lockfile) – pkgbuilds/1password-beta/.omarchy/package.json lists npm dependencies but omits a lockfile, risking non‑reproducible builds.
  • 94 test files and 77 documentation files provide coverage and guidance.
  • No secrets or credentials are committed.
  • License is present (LICENSE).
  • CI jobs are defined per package, ensuring isolated builds.

The Bottom Line

omarchy-pkgs delivers a clear, script‑driven workflow for Arch package maintenance across multiple channels and architectures. The structure is intuitive: one recipe per directory, a lightweight bin/ CLI, and a containerized build environment. Minor improvement: add npm lockfiles where .omarchy/package.json declares dependencies. The repo is ready for teams that need a reproducible, automated build pipeline for Omarchy packages.