UltiKits CI Workflows

Central reusable GitHub Actions CI workflows for the UltiKits Minecraft plugin monorepo. Implements the Candidate D contract family: two member types sharing one reusable workflow.

---

Contract Family Members

Member	Who uses it	JDK matrix	Spigot BuildTools
Non-NMS	Pure Spigot-API modules (no NMS submodules)	17, 21	No
NMS	Modules with an NMS submodule (e.g. UltiBot with *-v1_21_R1)	21 only	Yes (cache-gated)

Both members are served by the single reusable workflow at .github/workflows/maven-ci.yml. The needs-nms boolean input switches between the verify-non-nms and verify-nms jobs.

---

Caller Templates

Copy the appropriate file from callers/ into your module repo as .github/workflows/maven-ci.yml. Both templates pin to the floating major tag @v1 to auto-receive security re-pins; immutable tags (e.g. v1.1.0) remain available if you need strict pinning.

Non-NMS module

name: Maven CI
on:
  push:
    branches: ['**']
  pull_request:
permissions:
  contents: read
jobs:
  ci:
    uses: UltiKits/ci-workflows/.github/workflows/maven-ci.yml@v1
    with:
      needs-nms: false

NMS module (e.g. UltiBot)

name: Maven CI
on:
  push:
    branches: ['**']
  pull_request:
permissions:
  contents: read
jobs:
  ci:
    uses: UltiKits/ci-workflows/.github/workflows/maven-ci.yml@v1
    with:
      needs-nms: true
      mc-version: '1.21.1'
    secrets: inherit

secrets: inherit is required for the NMS path so that any Nexus credentials (dim-9 fallback) reach the reusable workflow.

---

Workflow Inputs Reference

Input	Type	Default	Description
needs-nms	boolean	false	Enable NMS path (BuildTools + single-JDK 21 run)
mc-version	string	"1.21.1"	Minecraft version passed to BuildTools
nms-java	string	"21"	JDK for BuildTools and NMS reactor compilation
non-nms-java	string	'["17","21"]'	JSON array of JDK versions for non-NMS matrix
provisioning	string	"buildtools"	buildtools (primary) or nexus (dim-9 fallback)
working-directory	string	"."	Maven project root relative to repo root
maven-args	string	""	Extra flags appended to mvn test and mvn package

---

Adding a New Minecraft Version (Dim 2)

Change the mc-version input in your NMS caller:

    with:
      needs-nms: true
      mc-version: '1.21.4'   # ← bump here only

The reusable workflow passes this directly to BuildTools and into the cache key. No changes to ci-workflows are required unless the BuildTools action itself needs an update.

---

Rollback Path — Nexus Fallback (Dim 9)

If BuildTools is broken or unavailable (e.g. Spigot servers down), switch the NMS caller to use the private Nexus mirror that already holds the remapped-mojang artifacts:

    with:
      needs-nms: true
      mc-version: '1.21.1'
      provisioning: nexus

The verify-nms job will skip the BuildTools step entirely and resolve org.spigotmc:spigot:<ver>:remapped-mojang as a normal Maven dependency from maven.wisdommee.com. Your caller's settings.xml (via secrets: inherit) must supply the Nexus credentials. Mirror population is a separate gate and not managed here.

---

Maintenance Boundary / When to Open a Redesign (Dim 10)

The current design handles:

• Single-module and multi-module pure-Spigot modules (non-NMS).
• Single-MC-version NMS submodules built with BuildTools or a Nexus mirror.
• JDK matrix for non-NMS (configurable via non-nms-java).

Open a redesign issue if any of the following arise:

• A module needs multiple concurrent NMS versions (e.g. both 1.20.4 and 1.21.1 in the same run) — the current NMS job is single-version.
• A module needs publish/deploy steps beyond test+package — extend the contract with a publish job or a separate reusable workflow.
• The SpraxDev/Action-SpigotMC action is no longer maintained or its pinned SHA (6419bc4…) needs updating — re-resolve and update the SHA here, then cut a new semver release.
• A module requires Windows or macOS runners — the current contract hard-codes ubuntu-latest.
• Dependency scanning, SBOM generation, or other security gates are added org-wide — those belong in a separate reusable workflow, not here.

---

Supply-Chain Pinning

All uses: references are pinned to immutable commit SHAs:

Action	Tag	Pinned SHA
actions/checkout	v5.0.1	93cb6efe18208431cddfb8368fd83d5badbf9bfd
actions/setup-java	v5.2.0	be666c2fcd27ec809703dec50e508c2fdc7f6654
actions/cache	v5.0.5	27d5ce7f107fe9357f9df03efb73ab90386fccae
SpraxDev/Action-SpigotMC	v5.3.0	6419bc4cdfb60d37bd3f541f6c8d5be60e6e0933

The actions/* steps run on the node24 runtime (v5 major line). Callers pinned to @v1 self-heal across future security re-pins.

When updating a pinned action, resolve the new SHA, update the workflow, and cut a new semver release of ci-workflows.

---

Security Notes

• The maven-args input is passed through an env: variable (MAVEN_ARGS) and referenced as $MAVEN_ARGS in shell, not interpolated directly into the run: script. This prevents shell injection from caller-supplied flags.
• The working-directory: key uses GitHub Actions' native field, not shell interpolation, so it is safe as-is.
• This workflow is workflow_call-only (no push/pull_request trigger of its own), so the only untrusted-input surface is caller repos — limit who can create callers in the org.
• Callers should specify permissions: contents: read (shown in templates above) to apply least-privilege to the calling workflow's token.

---

Versioning

Callers should pin to the floating major tag @v1 (recommended — auto-receives security re-pins) or, for strict pinning, an immutable tag (@v1.1.0) or full commit SHA. Tag @main is not recommended for production callers — main moves with every fix.

Current stable tags: floating @v1 → v1.1.0