The reviewed team index model#

This page explains a way to run a private Sysand index for a team: contributors submit packages through a pull or merge request, automation validates and publishes them, and review is the gate that decides what ships. The index is still a static file tree with no publish API: this replaces “one person runs sysand index add” with a reviewed, automated workflow.

Two ready-made example repositories implement everything described here; you copy one and configure it rather than building it from scratch. This page explains the model so you can decide whether it fits; each repository’s ADMINISTRATION.md is the actual setup and operations guide, and its README.md is written for the people who install and publish.

What you need#

  • A GitHub organization, or a GitLab group. On GitHub, protecting the generated index branch so that only the automation can write it relies on a ruleset bypass actor that is available in organization-owned repositories. On GitLab, serving the index privately requires GitLab 17.10 or later (token access to a members-only Pages site).

  • sysand for everyone who builds or installs packages.

How it works#

The repository has two branches with distinct jobs:

  • The default branch (main) holds a kpars/ folder of submitted packages, the automation, and the docs. People change it through pull or merge requests, like any normal repository.

  • A generated index branch holds the actual index files that sysand reads. Only the automation (the index-writer) writes to it; nobody edits it by hand.

Publishing a package is three steps for a contributor:

  1. Build a package: sysand build produces a .kpar file. Its .project.json must contain a publisher field, which, with the name and version, is what identifies the package on the index.

  2. Add that file to kpars/ in a pull or merge request. The file’s own metadata identifies it; no renaming or folder structure is required.

  3. A validation job runs on the request: it identifies each submission (publisher, name, version, license) and dry-runs the actual publish against the index, so a broken submission fails the check before anyone merges it.

On every push to the default branch (which, when it is protected, means on every merge) the index-writer reconciles the index branch against kpars/: it publishes any package not already in the index and skips the rest. It is idempotent, never removes anything, and never writes back to the default branch.

Consumers read the index from the index branch, served by the forge: raw.githubusercontent.com on GitHub, a private GitLab Pages site on GitLab. Installs use the same sysand add <IRI> --index <url> command as any other index, with a token for private access. The example repository’s README.md gives the exact credential setup.

What this model gives you#

  • Review is the publishing gate. Whoever can approve a pull or merge request decides what is published; there is no separate index-write credential for humans. Making the validation check required means a failing submission cannot be merged.

  • A record of every submission. Submitted .kpar files stay in kpars/; the folder is the history of what was published.

  • Immutability. A published version cannot be changed: the validation rejects modifying an already-submitted package. Publish a new version instead.

What it does not do#

  • It does not restrict which publisher names a submitter may use: the index does not track ownership of namespaces. Approvers are expected to check that a submission’s publisher and project name are ones the submitter is entitled to use.

  • It is not a dynamic index server. There is no sysand publish endpoint; publishing is always a reviewed change to a git repository.

Setting one up#

Copy the example repository for your forge and follow its ADMINISTRATION.md: