Release Process
Nexus is a monorepo with 41 package directories under packages/. Split packages are mirrored to their own GitHub repositories and published to Packagist independently. The split-and-publish pipeline is implemented in .github/workflows/split.yml, whose matrix currently lists all 41 packages (the nexus meta-package splits to the nexus-actors/meta repository).
How splits work
The pipeline uses splitsh-lite — a Go binary that extracts a sub-directory's git history into a standalone SHA. For each package:
splitsh-lite --prefix=packages/<local>reads the monorepo's full history and outputs a single commit SHA that represents only that package's subtree.- The SHA is pushed to the corresponding
nexus-actors/<remote>repository on GitHub (e.g.,nexus-actors/core,nexus-actors/runtime-fiber).
The split runs in a matrix job, one job per package, with fail-fast: false so a failure in one package does not block others.
Package mapping
Every matrix entry follows the same rule: packages/nexus-<name> splits to the nexus-actors/<name> repository (e.g., packages/nexus-core to nexus-actors/core, packages/nexus-worker-pool-swoole to nexus-actors/worker-pool-swoole). The authoritative list is the matrix.package block in .github/workflows/split.yml — 41 entries at the time of writing. When you add a package, add its matrix entry there (see Adding a package).
When the split runs
The workflow triggers on three events:
| Trigger | What happens |
|---|---|
Push to main after CI passes | Splits the main branch tip to each split repo |
Tag push (v*) | Splits and pushes the same tag to each split repo |
workflow_dispatch | Manual re-run (useful after fixing a split failure) |
The tag-push path is what Packagist uses: when you push v1.0.0 to the monorepo, the workflow pushes that tag to all 41 split repos, and Packagist picks up the new version within minutes.
Versioning convention
Nexus follows Semantic Versioning. All packages share the same version number — a v1.2.0 tag in the monorepo becomes v1.2.0 in every split repo simultaneously. Never release packages at different version numbers.
Cross-package constraints in the package manifests use versioned ^0.1 constraints (since v0.1.0). The split workflow copies manifests verbatim — it does not rewrite constraints when tagging — so keep sibling constraints aligned with the release line when bumping versions.
Before tagging any v* release, confirm the internal constraints match the release line (e.g., ^0.1 for 0.1.x tags), and install at least one leaf package from a clean fixture to prove the tagged set resolves.
To cut a release (once the constraints above are versioned):
git tag v1.2.0
git push origin v1.2.0
CI must be green on main before tagging. The split workflow verifies this via the workflow_run trigger's conclusion == 'success' gate.
Required secret
The workflow uses SPLIT_TOKEN — a GitHub personal access token with repo scope on all nexus-actors/* split repositories. This secret is stored in the monorepo's GitHub Actions secrets. Without it the push steps will fail with 403.
Manual re-run
If a split job fails (e.g., network error pushing to GitHub), re-run it via:
gh workflow run split.yml
Or navigate to Actions → Split Packages → Re-run jobs in the GitHub UI.
See also
- splitsh internals — lower-level explanation of splitsh-lite
- Adding a package — how to add a new package including the split.yml entry