The build system uses Docker to create a clean, reproducible build environment. Packages are built unsigned, then signed in a separate step, promoted to production, and synced to a remote server.

Directory Structure

omarchy-pkgs/
├── pkgbuilds/              # Source PKGBUILDs (one directory per package)
├── build-output/           # Temporary build workspace
├── pkgs.omarchy.org/       # Final signed packages
├── build/                  # Build scripts that run inside of the Docker container
├── bin/                    # Command-line tools
└── logs/                   # Build and operation logs

Quick Start

Complete Release Workflow

Build, sign, promote, clean, and sync in one command:

bin/repo release

With options:

bin/repo release --skip-prod-check              # Skip production confirmation
bin/repo release --sync-remote dev-pkgs:/       # Sync to dev remote instead
bin/repo release --package omarchy-nvim         # Build only one package

Step-by-Step Workflow

# 1. Build packages (unsigned)
bin/repo build

# 2. Sign all built packages (sitting in `build-output`)
bin/repo sign

# 3. Promote to production directory (copy from `build-output` -> `pkgs.omarchy.org`)
bin/repo promote

# 4. Clean old versions and update database
bin/repo clean

# 5. Sync to remote server
bin/repo sync pkgs.omarchy.org/x86_64

Commands

`bin/repo build`

Builds packages from pkgbuilds/ directory in a Docker container.

Options:

--package <name> - Build only a specific package
--arch <arch> - Target architecture (default: x86_64)

What it does:

Clears build-output/ directory
Builds packages in dependency order
Creates unsigned .pkg.tar.zst files in build-output/x86_64/
Skips packages that are already up-to-date in pkgs.omarchy.org/

Examples:

bin/repo build                         # Build all packages
bin/repo build --package omarchy-nvim  # Build only yay

`bin/repo sign`

Signs all unsigned packages in build-output/.

What it does:

Fetches GPG key and passphrase from env or 1Password
Signs all .pkg.tar.zst files

`bin/repo promote`

Copies signed packages from build-output/ to pkgs.omarchy.org/.

Options:

--arch <arch> - Target architecture (default: x86_64)
--dry-run - Preview what would be copied

What it does:

Copies all packages and signatures to production directory
Cleans up build-output/ after successful promotion

Examples:

bin/repo promote
bin/repo promote --dry-run

`bin/repo clean`

Removes old package versions and updates the repository database.

Options:

--keep N - Keep N versions of each package (default: 2)
--dry-run - Preview what would be removed
--usage - Show disk usage statistics

What it does:

Removes old package versions (keeps latest 2 by default)
Updates omarchy.db.tar.zst repository database
Shows disk usage and statistics

Examples:

bin/repo clean                      # Keep 2 versions
bin/repo clean --keep 3             # Keep 3 versions
bin/repo clean --dry-run            # Preview cleanup
bin/repo clean --usage              # Show disk usage

`bin/repo sync`

Syncs the repository to a remote server using rclone.

Arguments:

<directory> - Local directory to sync (e.g., pkgs.omarchy.org/x86_64)

Options:

--remote <remote> - Rclone remote destination (default: pkgs.omarchy.org:omarchy-pkgs)
--skip-prod-check - Skip production confirmation

What it does:

Syncs packages to remote (uses --ignore-existing to preserve versions)
Syncs database files with checksums
Prompts for confirmation when syncing to production

Examples:

bin/repo sync pkgs.omarchy.org/x86_64                    # Sync to production
bin/repo sync pkgs.omarchy.org/x86_64 --skip-prod-check  # Skip confirmation
bin/repo sync pkgs.omarchy.org/x86_64 --remote dev-pkgs:/# Sync to dev

`bin/repo release`

Runs the complete release workflow in sequence.

Options:

--package <name> - Build only a specific package
--arch <arch> - Target architecture (default: x86_64)
--sync-remote <path> - Rclone remote for sync (default: production)
--skip-prod-check - Skip production confirmation

What it does:

Builds packages
Signs packages
Promotes to production
Cleans old versions
Syncs to remote

Examples:

bin/repo release                                    # Full workflow
bin/repo release --skip-prod-check                  # Skip prod confirmation
bin/repo release --sync-remote dev-pkgs:/           # Sync to dev
bin/repo release --package omarchy-nvim             # Single package

Other Commands

bin/repo list - List all packages in the repository

bin/repo list

bin/repo remove <package> - Remove a package from the repository

bin/repo remove yay

bin/repo update - Update the repository database (usually done automatically by clean)

bin/repo update

Adding New Packages

From AUR

Add package name to build/packages/omarchy-aur.packages (for future syncing)
Sync PKGBUILD to local directory:
```
bin/sync-aur package-name
```

Build and release:

bin/repo release --package package-name

Maintaining Local Patches for AUR Packages

If you need to maintain local modifications to AUR packages that persist through aur-sync updates:

Create a patches/ directory inside the package directory:
```
mkdir pkgbuilds/package-name/patches
```

Create patch files for your modifications:

cd pkgbuilds/package-name
# Make your changes to PKGBUILD or other files
git diff > patches/my-fix.patch

When bin/sync-aur runs, it will automatically apply all .patch files found in the patches/ directory after syncing from AUR.

Example: The opencode package has patches/fix-parcel-watcher.patch which adds platform-specific @parcel/watcher installation to the build process.

Custom Package

Create directory in pkgbuilds/:
```
mkdir pkgbuilds/my-package
```
Add PKGBUILD and any additional files
Build and release:
```
bin/repo release --package my-package
```

Package Dependencies

The build system automatically handles dependencies between packages being built. For example, if aether depends on hyprshade, the build system will:

Detect the dependency relationship
Build hyprshade first
Add it to the omarchy-build temporary repository
Build aether (which can now install hyprshade from omarchy-build)

This works through two internal repositories:

omarchy-build - Temporary repo in build-output/ (unsigned packages, used during build)
omarchy - Production repo in pkgs.omarchy.org/ (signed packages)

Version Management

Packages are only rebuilt if:

PKGBUILD version is newer than the version in the repository DB
Package doesn't exist in production yet