Overview/x-repo — package repository

Publishing a Package

Publishing to the [x] pacman repository is a local build then commit flow. GitHub Actions never builds packages; it only deploys what is committed under public/ (see web-portal.md).

The full cycle: local build -> repo-add (+ optional signing) -> SHA256SUMS -> PR -> Pages deploy.

1. Local build

Requirements: an Arch-like environment with makepkg and repo-add available.

Package built from a PKGBUILD in this repo

Work on the package source, then build it inside its directory exactly as build-packages.sh does:

cd packages/x-release      # or packages/x-dev
makepkg -cf --noconfirm

This produces a .pkg.tar.zst (e.g. x-release-1.0-8-any.pkg.tar.zst) inside the package directory.

External package (x-scripts)

x-scripts is built in the sibling scripts repo (its PKGBUILD lives at scripts/packaging/), not here, and it ships the offline equisdots desktop snapshot used by the installer. Build it there:

cd scripts/packaging && makepkg -f

build-packages.sh imports the resulting ../scripts/packaging/x-scripts-*.pkg.tar.zst automatically and removes it from the build directory. You can also place the tarball directly in public/repo/x86_64/ before running the script. There is no packages/x-scripts/ source directory in this repo.

Native .xp packages (xpm/xpkg path)

The .xp endpoint under public/x/x86_64/ is out of scope for this flow: the automated native workflow is disabled and kept for reference in docs/build-x-native-workflow.md.

2. Regenerate the repository (repo-add)

From the repository root run:

./build-packages.sh              # builds x-release/x-dev + imports x-scripts + indexes
./build-packages.sh --index-only # skip the local builds (only import/index)

The script:

Rebuilds the configured PKGBUILD packages (x-release, x-dev) with makepkg unless --index-only is given.
Imports ../scripts/packaging/x-scripts-*.pkg.tar.zst when present and copies the freshly built x-release/x-dev tarballs into public/repo/x86_64/, deleting only those build artifacts. The committed leftovers under packages/xpm, packages/xpkg, packages/xfetch and packages/xtop are not touched.
Rebuilds the pacman database from scratch from every tarball in the directory (this also drops entries for packages that no longer exist):
```
repo-add -R x.db.tar.gz *.pkg.tar.zst
cp x.db.tar.gz x.db
cp x.files.tar.gz x.files
sha256sum * > SHA256SUMS
```
When X_REPO_SIGN_KEY is set, repo-add runs with -s -k instead, SHA256SUMS is signed and the keyring is re-exported; see Signing the repository.

Do not edit x.db or SHA256SUMS by hand; always regenerate them with this script (contributing rules in CONTRIBUTING.md also forbid manual database edits).

3. Review and commit

Check what changed under public/repo/x86_64/:

git status
git diff --stat

Expected changes for a package update:

the new .pkg.tar.zst (and removal of the replaced version),
regenerated x.db, x.db.tar.gz, x.files, x.files.tar.gz,
regenerated SHA256SUMS,
the PKGBUILD change itself under packages/.

For signed builds, also expect the detached signatures of the changed files:

*.pkg.tar.zst.sig for each (re)signed package,
x.db.sig/x.db.tar.gz.sig and x.files.sig/x.files.tar.gz.sig,
SHA256SUMS.sig,
signing.pub and trustedkeys.gpg when the keyring material changed.

Commit the repository changes, for example:

git add packages/x-release public/repo/x86_64
git commit -m "publish x-release 1.0-8"

4. Pull request

Per CONTRIBUTING.md the contribution flow is fork, branch, pull request against the main branch. Maintainers can also commit to a working branch and open the PR directly. Merge to main once CI/validation passes.

5. Deploy to GitHub Pages

After the changes are on main, deploy the site so the new repository files go live:

Go to the Actions tab of equislinux/x-repo.
Run the "Deploy Website to GitHub Pages" workflow (build.yml) manually via workflow_dispatch.
The workflow runs npm ci && npm run build (static export of the Next.js site including everything from public/), sanity-checks that x.db and an x-release tarball exist, then uploads ./out to GitHub Pages.

The updated packages are now served at:

https://equislinux.github.io/x-repo/repo/x86_64/ (pacman [x] repo)

Caveats

Do not run two Pages deployment workflows at once; they would overwrite each other's deployment (a pages concurrency group is defined in build.yml, and docs/build-x-native-workflow.md warns the same for the native workflow, which is disabled).
Keep the repository in sync with its consumers: x-release and x-dev are installed from this repo during the X distro install, and x-scripts must match the payload revision expected by the installer.

Signing the repository (X_REPO_SIGN_KEY)

Signing is optional and driven by a single environment variable, X_REPO_SIGN_KEY (the fingerprint or key ID of the project key). The repository is currently signed on the feat/signing branch (x-scripts 0.1.0-19 included), while the ISO still configures [x] as Optional, so verification is not enforced yet.

With the variable exported, build-packages.sh:

signs every package tarball — locally built ones via makepkg --sign --key "$X_REPO_SIGN_KEY", the imported x-scripts one via gpg --detach-sign — producing a detached *.pkg.tar.zst.sig per package;
runs repo-add -s -k "$X_REPO_SIGN_KEY", so x.db/x.files are signed, and mirrors x.db.sig/x.files.sig from the .tar.gz signatures;
signs SHA256SUMS, producing SHA256SUMS.sig;
exports the public keyring as trustedkeys.gpg and signing.pub into public/repo/x86_64/.

Without X_REPO_SIGN_KEY the script keeps publishing the repository unsigned and prints a warning. Commit the regenerated signature files and keyring next to the database and tarballs.

The complete procedure (key setup, consumer SigLevel/pacman-key configuration, pending ISO integration and key rotation) is in signing.md.

Edit this page on GitHub