setup-maelstrom

Install and validate a pinned Maelstrom distribution for a later GitHub Actions step.

The current contract is deliberately narrow: Ubuntu 24.04 x64, Maelstrom 0.2.4, and an exact Temurin LTS runtime. Other Linux distributions, Ubuntu versions, operating systems, architectures, and Maelstrom releases are unsupported until they have been exercised and given their own verified identities. The contract is continuously exercised on GitHub-hosted ubuntu-24.04 runners.

Usage

Pin the Action itself to a full commit SHA and independently pin the Maelstrom archive:

- name: Set up Maelstrom
  id: maelstrom
  uses: zactionsz/setup-maelstrom@<full-commit-sha>
  with:
    version: "0.2.4"
    sha256: "301ec71d6b12af0d765edb413f5cf5aa1046b5609bd4e31376a0b549548e5799"
    java-version: "21.0.11+10.0.LTS"
    analysis-tools: "true"

- name: Run a workload
  run: maelstrom test ...

analysis-tools: "false" installs Maelstrom and its Java runtime only. analysis-tools: "true" also installs and independently probes Graphviz (dot) and Gnuplot.

Outputs

Output	Value
version	Verified Maelstrom release version
path	Absolute path to the verified maelstrom launcher
maelstrom-root	Absolute path to the verified distribution root
sha256	Verified lowercase archive SHA-256
java-home	Absolute path to the verified Temurin runtime
analysis-tools	true only when Graphviz and Gnuplot were requested and probed

The Maelstrom root is added to PATH and exported as MAELSTROM_ROOT for later steps. A job summary records the exact archive, launcher, JAR, Java, Graphviz, and Gnuplot identities.

Security and failure behavior

Installation uses bounded, three-attempt retries. Each archive fetch and tar operation has a two-minute deadline; each apt operation has a five-minute deadline. Nothing is exported until all requested components pass their checks.

The Action rejects:

• a digest other than the recorded 0.2.4 release digest;
• a corrupt or truncated download;
• path traversal, links, special files, duplicate entries, or a changed archive manifest;
• a launcher or JAR whose SHA-256 does not match the recorded release;
• a Java version, build, vendor, or architecture identity mismatch; and
• either missing analysis tool when analysis-tools is enabled.

The upstream archive is downloaded directly from the Maelstrom GitHub release. The Action does not run maelstrom test, accept workload commands, or mirror Maelstrom's CLI. Workloads belong in explicit later workflow steps.

Development

npm ci
npm run check
actionlint

The reviewed source and tests are strict TypeScript. npm run build emits the committed, dependency-free JavaScript runtime in dist/; CI rejects generated runtime drift. The Action code is MIT licensed; Maelstrom remains licensed by its upstream authors.