logos-modules-release-base

A fork-me starting point for running your own Logos module catalog.

Fork this repo, add your modules as submodules, push — and you have a working module repository that the Logos clients (lgpd, the package_downloader module, the package-manager UI) can install from.

All the release machinery lives in the versioned, reusable logos-co/logos-modules-release-action. This repo only holds your submodules, your catalog metadata, and a thin layer of workflows that call the action. The canonical production catalog, logos-co/logos-modules-v2, is built exactly this way.

Quick start

1. Fork this repo (GitHub → Use this template / Fork).

2. Edit logos-repo.json — this is how clients identify your catalog. Replace every CHANGE-ME and set indexUrl to point at your fork:

   {
     "schemaVersion": 1,
     "name": "my-modules",
     "displayName": "My Modules",
     "description": "My personal Logos modules.",
     "homepage": "https://example.com",
     "indexUrl": "https://github.com/<your-owner>/<your-repo>/releases/download/index/index.json",
     "trustedSigners": []
   }

3. Add your modules:

   git clone https://github.com/<your-owner>/<your-repo>
   cd <your-repo>
   ./scripts/add-module.sh https://github.com/<you>/<your-module-repo>
   git add -A && git commit -m "Add <your-module-repo>" && git push

   add-module.sh registers the submodule and generates its per-module release workflow. Repeat for each module.

4. Publish. From the repo's Actions tab, run Release all modules (or an individual Release <module>) — or, from a terminal, ./scripts/catalog.sh release-all. The action builds each .lgx, verifies it, optionally signs it, cuts a <module>-v<version> GitHub release, and rolls everything up into the index release that clients read.

5. Point a client at it. Add your fork's logos-repo.json raw URL as a repository in the package-manager UI / lgpd:

   https://raw.githubusercontent.com/<your-owner>/<your-repo>/<default-branch>/logos-repo.json
   

That's it. Bumping a submodule pointer (which moves its metadata.json#version) and re-running its workflow publishes a new version; clients pick it up on their next catalog refresh.

Layout

.
├── logos-repo.json                       # YOUR catalog metadata — edit this
├── .gitmodules                           # submodule declarations (starts empty)
├── submodules/                           # one git submodule per module (you add these)
├── scripts/
│   ├── add-module.sh                     # add a submodule + generate its workflow
│   └── catalog.sh                        # run the catalog workflows via `gh` (no Actions tab)
└── .github/workflows/
    ├── _release-module.yml               # signing config — the ONE place to edit it
    ├── release-module.yml.template       # per-module workflow template (don't run; it's a template)
    ├── release-all.yml                   # umbrella; discovers modules from .gitmodules
    ├── rebuild-index.yml                 # rebuilds index.json after each release
    └── unpublish.yml                     # manually remove a module / version from the catalog

Workflow architecture

Two-tier reusable workflows so the signing pipeline lives in exactly one place:

• _release-module.yml — local private reusable workflow (workflow_call only, so it never shows up as runnable in the Actions UI). Calls logos-co/logos-modules-release-action/.github/workflows/release.yml@v1 with this catalog's signing configuration.
• release-<module>.yml — one per module, generated by add-module.sh. Each just passes module_path: submodules/<repo> to _release-module.yml. Lets you cut a single module from the Actions UI.
• release-all.yml — umbrella. Discovers the module list from .gitmodules at run time (no hand-maintained matrix) and fans out to _release-module.yml per module in parallel.
• rebuild-index.yml — thin passthrough to the action's index-rebuilder. Auto-triggered after each release; also runs on a 6-hourly catch-up schedule.
• unpublish.yml — manual (Actions tab). Removes a whole module or one specific version: deletes the release(s) + optionally their tags, then rebuilds the index. Run with dry_run: true first — deletion is irreversible. Re-running a release for an unchanged submodule is a fast no-op (the action skips builds whose <module>-v<version> is already published).

Every workflow declares permissions: contents: write because a forked repo's default GITHUB_TOKEN is read-only, and the release job must create releases / upload assets.

To change signing for the whole catalog, edit _release-module.yml only — the per-module callers and the umbrella never need touching.

Signing

Ships unsigned (signing_mode: none) so a fresh fork works immediately. When you're ready to sign, follow the inline instructions at the top of .github/workflows/_release-module.yml:

Mode	What runs	Where the key lives
none (default)	nothing	n/a — unsigned releases
inline	lgx sign in CI	LOGOS_SIGNING_KEY Actions secret (Ed25519 JWK)
external	your signing_command	anywhere (Jenkins / HSM / hardware token)

For inline, also put the matching public DID under trustedSigners in logos-repo.json so clients trust your signature.

Pinning the action version

The workflows reference …/release.yml@v1 — a moving tag tracking the latest 1.x of the action. For reproducible releases, pin an exact tag (e.g. @v1.2.3) instead. A bump to @v2 signals a breaking change to the workflow inputs or the index schema; stay on @v1 until you've read its migration notes.

Managing index.json without GitHub Actions

If you'd rather host .lgx files yourself (S3, your own server, a file share — anywhere lgpd can GET from) and not rely on this repo's GitHub-Actions index builder, logos-co/logos-modules-release-tool ships a single-file CLI (index.py) that builds, edits and validates an index.json from a plain list of .lgx URLs (or local files for packages you've just uploaded yourself). The output is byte-compatible with what rebuild-index.yml here produces, so clients consume it identically.

The GitHub Actions path in this repo stays the default — the tool is for catalog maintainers who want a fully non-GitHub setup, or who want local control over partial / incremental index edits.

Notes for cloning a fork

.gitmodules is committed but submodule working trees are not — after cloning your fork, run:

git submodule update --init --recursive