Mod Template

.github/workflows/modGlobalBuild.yml

Source: .github/workflows/modGlobalBuild.yml · reusable workflow

Run the DreamWeave Mod Template pipeline: validate a site's projects, record releases in the protocol manifest, and build and deploy the site.

Intended for: Mod Template sites directly, and Rust repositories through rustGlobalBuild or libGlobalBuild with mod_template.

Release behavior#

Runs the consumer's own ./buildSite, in one job per path. site (branches and pull requests) validates, tests and builds; on the default branch it also records what crates.io and GitHub published, signs and publishes the development release (mods only), and hands the site to deploy. release (tags) validates, packs a Jess application with the jess image when jess_application names one, builds, signs, records mod.lock on the default branch, publishes a mod's release, and starts a default-branch run of the calling workflow. With rust_release it publishes nothing of its own.

Artifacts and effects#

  • mod.lock commits on the default branch
  • Protocol manifests and the site on GitHub Pages
  • Mod archives, Jess applications (a .jsw and an executable per platform), Sigstore bundles and GitHub Releases (mods only)
  • Nexus uploads for mods with a file group, and for applications each platform's zip to the file group NEXUS_GROUP_IDS names for it

Assumptions and permissions#

  • The caller grants actions: write (the refresh run), contents: write, id-token: write and pages: write.
  • The consumer's ./buildSite, tools/ and templates come from the Mod Template; the workflow never supplies its own copy.
  • Keyless signatures name this workflow at its tag, so DREAMWEAVE_SIGNING_IDENTITY moves with every version bump.
  • record-crates reads the crates.io index and downloads each .crate it records.

Failure modes#

  • mod.lock push rejected: the default branch is protected against GitHub Actions.
  • A binary release is refused when an archive listed in [[platforms]] is missing from the staged github-release artifacts.
  • A jpk project with an application fails its release when jess_application is unset or names another file: the template finds nothing in dist/application.
  • A .crate whose SHA-256 differs from the crates.io index checksum is never recorded; rerun, then report it.

Example#

Mod sites use the generated Mod Template caller; Rust sites set mod_template: true on their application or library caller.

Inputs#

NameTypeRequiredDefaultDescription
jess_applicationstringfalseThe name a jpk project's mod.toml gives its application ([package] application), when it has one. A tag packs the repository's jess workspace into dist/application with the jess image first: <name>.jsw and an executable per platform jess is released for, which the template records.
rust_archivesbooleanfalsefalseThe calling workflow staged program archives as github-release-* artifacts in this run. Record them.
rust_releasebooleanfalsefalseThe calling StroggForge workflow built and published this run's release. Record it without publishing anything, and leave GitHub releases alone.

Secrets#

NameTypeRequiredDefaultDescription
NEXUS_API_KEY—false——
NEXUS_GROUP_IDS—false——

Permissions#

Top-level: {"contents":"read"}. Undeclared means inherited from the caller, not "none needed".

Job dependency graph#

Edges are YAML needs; conditional jobs may not run. Conditions are listed below.

workflow-modGlobalBuild relationship diagram. Its textual ledger or workflow contract is on this page or linked below.
workflow modGlobalBuild · Mermaid source · Full-size SVG
Read diagram source
flowchart TD
  n_deploy["deploy"]
  n_nexus_upload["nexus-upload"]
  n_release["release"]
  n_site["site"]
  n_site --> n_deploy
  n_release --> n_nexus_upload

Jobs#

JobNeedsRunner / delegateContainer / strategyCondition
deploysiteubuntu-24.04 / —— / —github.event_name != 'pull_request' && github.ref_name == github.event.repository.default_branch
nexus-uploadreleaseubuntu-24.04 / —— / {"matrix":{"upload":"${{ fromJson(needs.release.outputs.nexus) }}"}}needs.release.outputs.nexus != '[]'
releaseubuntu-24.04 / —— / —github.ref_type == 'tag'
siteubuntu-24.04 / —— / —github.ref_type != 'tag'

Steps#

deploy#

StepAction / commandCondition
Deployactions/deploy-pages@v5—

nexus-upload#

StepAction / commandCondition
—actions/download-artifact@v8—
—Nexus-Mods/upload-action@main—

release#

StepAction / commandCondition
—actions/checkout@v7—
—actions/checkout@v7—
—DreamWeave-MP/StroggForge/.github/actions/jess-setup@v72—
Restore the template packages the site pinsbash .stroggforge/scripts/mod-template/sync-pins.sh "$DEFAULT_BRANCH" false—
Validate every projectjess workspace run --trusted dreamweave-check—
Collect the archives the Rust workflow publishedactions/download-artifact@v8inputs.rust_archives
Pack the Jess applicationif [[ ! "$APPLICATION" =~ ^[A-Za-z0-9][A-Za-z0-9.-]*$ ]]; then echo "::error::jess_application '$APPLICATION' must be a file name: letters, digits, '.', '' and '-'" exit 1 fi mkdir -p dist/application docker run --rm --user "$(id -u):$(id -g)" --volume "$PWD:/work" --workdir /work "$JESS_IMAGE" \ workspace pack --output "dist/application/$APPLICATION.jsw" --runtimes /opt/jess/runtimesinputs.jess_application != ''
Build the release from the tagjess workspace run --trusted dreamweave-release -- "$TAG" if [ -f dist/release.json ]; then echo "recorded=true" >> "$GITHUB_OUTPUT"; else echo "recorded=false" >> "$GITHUB_OUTPUT"; fi—
Check whether anything asks to be signedif [ -s dist/sign.txt ]; then echo "needed=true" >> "$GITHUB_OUTPUT"; else echo "needed=false" >> "$GITHUB_OUTPUT"; fisteps.build.outputs.recorded == 'true' && !inputs.rust_release
—sigstore/cosign-installer@v3steps.signing.outputs.needed == 'true'
Sign archives with Sigstore (keyless)while IFS= read -r archive; do cosign sign-blob --yes --bundle "$archive.sigstore.json" "$archive" done < sign.txtsteps.signing.outputs.needed == 'true'
Record the release in mod.lock on the default branchbash .stroggforge/scripts/mod-template/commit-records.sh "$DEFAULT_BRANCH"—
Publish the GitHub releaserelease=$(cat dist/github-release) shopt -s nullglob files=(dist/.zip dist/.jpk dist/.jsw dist/.sigstore.json) if gh release view "$release" --repo "$REPOSITORY" >/dev/null 2>&1; then gh release upload "$release" "${files[@]}" --clobber --repo "$REPOSITORY" gh release edit "$release" --notes-file dist/release-notes.md --repo "$REPOSITORY" else title=$(jq -r '"(.name) (.release.version)"' dist/release.json) gh release create "$release" --verify-tag --draft --title "$title" --notes-file dist/release-notes.md --repo "$REPOSITORY" gh release upload "$release" "${files[@]}" --repo "$REPOSITORY" gh release edit "$release" --draft=false --repo "$REPOSITORY" fisteps.build.outputs.recorded == 'true' && !inputs.rust_release
Read the Nexus Mods uploadsbash .stroggforge/scripts/mod-template/nexus-uploads.shsteps.build.outputs.recorded == 'true' && !inputs.rust_release
—actions/upload-artifact@v7steps.nexus.outputs.uploads != '' && steps.nexus.outputs.uploads != '[]'
Start a default-branch run, which lists the release on the site# github.workflow_ref names the calling workflow: owner/repo/.github/workflows/<file>@<ref> workflow=${CALLER%%@} workflow=${workflow##/} gh workflow run "$workflow" --ref "$DEFAULT_BRANCH" --repo "$REPOSITORY"—

site#

StepAction / commandCondition
—actions/checkout@v7—
—actions/checkout@v7—
—DreamWeave-MP/StroggForge/.github/actions/jess-setup@v72—
Make a copy of the template a sitebash .stroggforge/scripts/mod-template/scaffold.sh "$DEFAULT_BRANCH"env.PUBLISHING == 'true' && github.repository != 'DreamWeave-MP/DreamWeave-Mod-Template' && !github.event.repository.fork
Restore the template packages the site pinsbash .stroggforge/scripts/mod-template/sync-pins.sh "$DEFAULT_BRANCH" "$PUBLISHING"—
Validate every projectjess workspace run --trusted dreamweave-check—
Record releases published to crates.io and GitHubbash .stroggforge/scripts/mod-template/commit-records.sh "$DEFAULT_BRANCH"env.PUBLISHING == 'true'
Find the published site's URLactions/configure-pages@v6env.PUBLISHING == 'true'
Choose the base URLif [ -n "$PAGES_URL" ]; then echo "url=$PAGES_URL" >> "$GITHUB_OUTPUT" else echo "url=$(sed -n 's/^base_url *= "(.)"/\1/p' config.toml | head -1)" >> "$GITHUB_OUTPUT" fi—
Collect the archives the Rust workflow publishedactions/download-artifact@v8inputs.rust_archives && github.event_name != 'pull_request'
Package development builds, build the site, and check itjess workspace run --trusted dreamweave-build -- "$BASE_URL" jess workspace run --trusted dreamweave-site -- public "$BASE_URL" jess workspace run --trusted dreamweave-links -- public "$BASE_URL"—
Check whether anything asks to be signedif [ -s dist/sign.txt ] && [ "$PUBLISHING" = true ] && [ "$MOD_RELEASE" = true ]; then echo "needed=true" >> "$GITHUB_OUTPUT" else echo "needed=false" >> "$GITHUB_OUTPUT" fi—
—sigstore/cosign-installer@v3steps.signing.outputs.needed == 'true'
Sign development archives with Sigstore (keyless)while IFS= read -r archive; do cosign sign-blob --yes --bundle "$archive.sigstore.json" "$archive" done < sign.txtsteps.signing.outputs.needed == 'true'
Publish the development releaserelease=$(cat dist/github-release) shopt -s nullglob files=(dist/.zip dist/.jpk dist/.jsw dist/.sigstore.json) if gh release view "$release" --repo "$REPOSITORY" >/dev/null 2>&1; then gh release delete "$release" --yes --repo "$REPOSITORY" fi gh api -X DELETE "repos/$REPOSITORY/git/refs/tags/$release" >/dev/null 2>&1 || true if [ ${#files[@]} -eq 0 ]; then echo "No project publishes a development build." exit 0 fi gh release create "$release" --prerelease --draft --target "$GITHUB_SHA" --title "Development build" \ --notes "The default branch at $GITHUB_SHA, built by $RUN_URL. It may be ahead of the last release, and it may be broken." \ --repo "$REPOSITORY" gh release upload "$release" "${files[@]}" --repo "$REPOSITORY" gh release edit "$release" --draft=false --repo "$REPOSITORY"env.PUBLISHING == 'true' && !inputs.rust_release
—actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9env.PUBLISHING == 'true'