Packaging, signing and release
Every app ships the same way: a version tag on a commit whose tests passed builds the installers for five targets, each on its own runner, signs the macOS and Linux downloads, attests every one, and publishes them in one GitHub release, with Homebrew and winget packages where the app has them. The workflows that do it share one posture (actions pinned to a commit, the least permissions, a timeout on every job) and leave their results readable after the run. A user gets the same kind of download, checked the same way, for any app on any OS (principle 1).
Rules on this page 31
| ID | Level | Rule |
|---|---|---|
| Targets | ||
| REL-01 | MUST | jpackage builds the installers for five targets, Linux x64 and arm64, macOS arm64 and x64,
and Windows x64, each on its own runner, through a Maven profile that packages the app ( dist in Editora).
|
| REL-02 | SHOULD | Downloads are named <App>-<version>-<target>.<ext>.
|
| REL-03 | MUST | |
| REL-04 | SHOULD | The release notes are the version’s section of CHANGELOG.md.
|
| REL-05 | MUST | The Maven version is the single source of truth: a tag vX.Y.Z releases the version in
pom.xml.
|
| REL-06 | SHOULD | The default branch carries a -SNAPSHOT version, and a post-release job opens the pull
request that bumps it to the next snapshot.
|
| REL-07 | SHOULD | A release-asset check fails the run before publishing when an expected file is missing.
|
| REL-08 | SHOULD | On Linux, a .desktop file’s StartupWMClass is the JavaFX app class.
|
| REL-09 | SHOULD | On Linux, AppStream metainfo has the id io.github.adriandeleon.<App>.
|
| REL-10 | SHOULD | Packaging trains an AOT cache (JDK 25 Leyden) to cut start-up time; Linux legs run the
training under xvfb.
|
| Install methods | ||
| REL-11 | MUST | The GitHub release offers every download of every target: the .dmg, .msi, .deb,
.rpm, .AppImage and .tar.gz, with checksums. Which target gets which type is under Targets.
|
| REL-12 | SHOULD | On macOS (Apple Silicon) the app installs with
brew install --cask adriandeleon/tap/<app>: JReleaser’s brew packager writes the cask to
adriandeleon/homebrew-tap. A cask takes exactly one artifact,
so it serves Apple Silicon, and Intel Macs use the macos-x64 DMG.
|
| REL-13 | SHOULD | On Windows x64 the app installs with winget install AdrianDeLeon.<App>: JReleaser’s
winget packager opens a pull request on microsoft/winget-pkgs
from the adriandeleon fork. The package identifier is AdrianDeLeon.<App>, the moniker the app’s lower-case
name.
|
| REL-14 | SHOULD | |
| Signing | ||
| REL-15 | MUST | The macOS .dmg is signed with the Developer ID Application certificate (team 8JKSF797L8),
with the hardened runtime and per-app entitlements, notarized with notarytool, stapled and checked with
spctl; then the notarized app is launched once.
|
| REL-16 | MUST | Linux downloads are signed with the one shared OpenPGP release key (“Adrian De Leon (release
signing)”) in a job of their own, apart from the build legs ( sign-linux in Editora): rpmsign for the .rpm, a
debsigs origin signature for the .deb, and an armored .asc beside every file. The public key is committed as
packaging/linux/signing-key.asc and attached to each release.
|
| REL-17 | SHOULD | The Windows .msi is signed with Authenticode, once the certificate is chosen.
|
| REL-18 | MUST | Every download has a GitHub build provenance attestation
( actions/attest-build-provenance), which gh attestation verify checks.
|
| CI/CD (GitHub Actions) | ||
| REL-19 | MUST | The CI workflow ( ci.yml in Editora) runs on every push to the default branch and every pull
request, with two checks: the format check of PLAT-10 (spotless:check; the job Editora
names Format) and the build with its tests (./mvnw verify, coverage gate included; Editora’s Build &
Test), on the JDK PLAT-01 names. Both are required status checks for the default branch.
|
| REL-20 | MUST | The tests run on all three OSes: the pure suite (no JavaFX toolkit) on Linux, macOS and
Windows, and the FX suite on Linux and at least one more. They run there every day or on every pull request. How
the runs are split is the app’s own: one workflow that runs everything on every pull request meets this, and so
does a quick workflow for pull requests with a fuller one on a schedule. A release waits for these runs on its own
commit, on all three OSes: that it waits at all is REL-30.
|
| REL-21 | MUST | The release workflow ( release.yml in Editora) runs on a version tag (v* meets it; the
version-shaped v[0-9]+.[0-9]+.[0-9]+* is the better pattern, since a tag like vendor-import doesn’t match
it), with workflow_dispatch as a dry run that builds and signs and publishes nothing. The tag matching the pom
is REL-05, the tests it waits for REL-30, the release-asset check REL-07, and the
bump to the next snapshot REL-06.
|
| REL-30 | MUST | A release is cut only from a commit whose tests passed: the release workflow runs the suite
before it builds the installers, or a preflight job reads CI’s result for the tagged commit and stops when it is
not green.
|
| REL-22 | MUST | Every workflow pins each third-party action to a commit SHA, with its version in a comment
( actions/setup-java@b843ebf… # v6.1.0).
|
| REL-23 | MUST | Dependabot updates github-actions and maven weekly.
|
| REL-24 | MUST | Every workflow starts from permissions: contents: read, or from less; only a job that needs
write access asks for it, in its own block.
|
| REL-25 | SHOULD | Every actions/setup-java step caches Maven’s repository (cache: maven). The JDK it sets
up is PLAT-01’s.
|
| REL-26 | MUST | Every job that runs steps has timeout-minutes. A job that calls a reusable workflow
(uses: in place of steps:) takes no timeout-minutes: GitHub does not accept the key there, and the called
workflow’s own jobs carry theirs.
|
| REL-31 | MUST | Every workflow that runs on pull requests has a concurrency group that cancels a superseded
pull-request run, and never a run on the default branch.
|
| REL-27 | MUST | A CI run leaves its results where they can be read without running it again: it uploads the
surefire reports even when tests fail, uploads the JaCoCo report, and writes the coverage totals to the job
summary.
|
| REL-28 | MUST | Signing skips cleanly when the secrets are absent (forks, dry runs), so they still build; a tag
without them fails.
|
| REL-29 | MUST | The packaged app is launched once on each OS before a release (a smoke test).
|
Targets
Section titled “Targets”Each target builds on its own GitHub-hosted runner. jpackage and JavaFX natives are host-specific, so there is no cross-building.
| Target | Runner | Downloads |
|---|---|---|
| Linux x64 | ubuntu-latest | .deb, .rpm, .AppImage, .tar.gz, fat jar |
| Linux arm64 | ubuntu-24.04-arm | .tar.gz (and .deb where the app’s tooling allows), fat jar |
| macOS arm64 | macos-15 | .dmg |
| macOS x64 | macos-15-intel | .dmg (the last Intel image, good to about Aug 2027) |
| Windows x64 | windows-latest | .msi, fat jar |
| Windows arm64 | — | Not possible yet: OpenJFX publishes no win-aarch64 natives (JDK-8314064). ARM users run the x64 MSI under emulation. |
The fat jar is Editora’s and the template’s: only their release workflows build one (-Pfatjar), on the Linux and
Windows legs. Termina, Torrenta, Mirada, Modula and nux release none.
- REL-01 MUST jpackage builds the installers for five targets, Linux x64 and arm64, macOS arm64 and x64,
and Windows x64, each on its own runner, through a Maven profile that packages the app (
distin Editora).- Check (code): the release workflow’s build matrix has a leg for each of the five targets (
linux-x64,linux-arm64,macos-arm64,macos-x64andwindows-x64in Editora), each on a runner of that OS and architecture, and each leg builds with a profile ofpom.xmlthat runs jpackage, whatever the profile is called. The runner images under Targets are Editora’s: another image of the same OS and architecture meets it (Termina, Torrenta, Mirada, Modula and nux build macOS arm64 onmacos-latest). - Reference: Editora
release.yml(thebuildjob),pom.xml(dist). The template and the five other apps name their profiledisttoo.
- Check (code): the release workflow’s build matrix has a leg for each of the five targets (
- REL-02 SHOULD Downloads are named
<App>-<version>-<target>.<ext>.- Check (code): the release-asset check builds the expected names this way.
- Reference: Editora
scripts/release/CheckRelease.java(expectedAssets).
- REL-03 MUST JReleaser (
jreleaser.yml) builds nothing: it creates the GitHub release, attaches every file andchecksums_sha256.txt, and runs the packagers of REL-12 and REL-13 where the app has them.- Check (code):
jreleaser.ymlhas no step that compiles or packages the app: it attaches the build matrix’s files and the checksums file, and itsbrewandwingetpackagers, where the app has them, take those same files. The job that runs it needs the build jobs. - Reference: Editora
jreleaser.yml, thereleasejob inrelease.yml.
- Check (code):
- REL-04 SHOULD The release notes are the version’s section of
CHANGELOG.md.- Check (code): the release job gives that section to the step that publishes (JReleaser, by REL-03) as the release’s notes.
- Reference: Torrenta
scripts/release/ReleaseNotes.java. Editora’s release notes are still its commit list.
- REL-05 MUST The Maven version is the single source of truth: a tag
vX.Y.Zreleases the version inpom.xml.- Check (code): the release workflow fails when the tag and the pom version differ.
- Reference: Editora’s “Check the tag against the pom version” step in
release.yml.
- REL-06 SHOULD The default branch carries a
-SNAPSHOTversion, and a post-release job opens the pull request that bumps it to the next snapshot.- Check (code): the pom’s version on the default branch ends in
-SNAPSHOT, andrelease.ymlhas the bump job. - Reference: Editora’s
bumpjob inrelease.yml.
- Check (code): the pom’s version on the default branch ends in
- REL-07 SHOULD A release-asset check fails the run before publishing when an expected file is missing.
- Why: GitHub releases are immutable.
- Check (code): a step before the one that publishes compares the gathered files with the expected list.
- Reference: Editora’s “Verify the expected release assets” step in
release.yml.
- REL-08 SHOULD On Linux, a
.desktopfile’sStartupWMClassis the JavaFX app class.- Why: the running window then belongs to the menu entry and shows its icon.
- Check (code):
packaging/linux/<App>.desktopsetsStartupWMClassto the fully qualified name of the app’s own class that extendsApplication:com.editora.Appin Editora,com.modula.ModulaAppin Modula. - Reference: Editora
packaging/linux/Editora.desktop, Torrentapackaging/linux/Torrenta.desktop, Modulapackaging/linux/Modula.desktop. The template, Termina, Mirada and nux set theirs the same way.
- REL-09 SHOULD On Linux, AppStream metainfo has the id
io.github.adriandeleon.<App>.- Check (code):
packaging/linux/io.github.adriandeleon.<App>.metainfo.xmlcarries that<id>. - Reference: Torrenta
packaging/linux/. Editora’s metainfo id (com.editora.Editora) predates the rule.
- Check (code):
- REL-10 SHOULD Packaging trains an AOT cache (JDK 25 Leyden) to cut start-up time; Linux legs run the
training under
xvfb.- Check (code): the packaging build (Editora’s
distprofile) runs a training launch with-XX:AOTCacheOutput, and the Linux release legs installxvfb. - Reference: Editora
scripts/aot_build.java; Termina’s and Mirada’sscripts/aot-train.sh.
- Check (code): the packaging build (Editora’s
Install methods
Section titled “Install methods”- REL-11 MUST The GitHub release offers every download of every target: the
.dmg,.msi,.deb,.rpm,.AppImageand.tar.gz, with checksums. Which target gets which type is under Targets.- Check (code): the files the release attaches include each of these types and a checksums file: the files
jreleaser.ymllists or, in a workflow that publishes another way, the ones its publishing step uploads. That JReleaser is what publishes is REL-03. - Reference: Editora
jreleaser.yml.
- Check (code): the files the release attaches include each of these types and a checksums file: the files
- REL-12 SHOULD On macOS (Apple Silicon) the app installs with
brew install --cask adriandeleon/tap/<app>: JReleaser’sbrewpackager writes the cask toadriandeleon/homebrew-tap. A cask takes exactly one artifact, so it serves Apple Silicon, and Intel Macs use themacos-x64DMG.- Why: the official homebrew-cask repository has notability rules a new project does not meet, so the family shares one personal tap.
- Check (code):
jreleaser.ymlhas abrewpackager for that tap;jreleaser package --basedir .writes the cask locally, to check it without releasing. - Reference: Torrenta and Termina
jreleaser.yml; Editora has no packager yet.
- REL-13 SHOULD On Windows x64 the app installs with
winget install AdrianDeLeon.<App>: JReleaser’swingetpackager opens a pull request onmicrosoft/winget-pkgsfrom theadriandeleonfork. The package identifier isAdrianDeLeon.<App>, the moniker the app’s lower-case name.- Check (code):
jreleaser.ymlhas awingetpackager with that identifier;jreleaser package --basedir .writes the manifests locally. - Reference: Torrenta and Termina
jreleaser.yml; Editora has no packager yet.
- Check (code):
- REL-14 SHOULD The Homebrew and winget packagers (REL-12, REL-13) read one
repository secret, a classic personal access token with
reposcope (PACKAGES_TOKENin Torrenta, Termina and the app template). Without it JReleaser skips both packagers, and the GitHub release still publishes.- Why: the workflow’s own token cannot write to the tap or open a pull request on the fork.
- Check (code): the release workflow passes a secret of the repository to JReleaser as the two packagers’ token, whatever the secret is called, and leaves both packagers out when it is empty.
- Reference: the publishing jobs of Torrenta’s
release.yml, Termina’srelease.ymland the app template’srelease.yml, which readPACKAGES_TOKENand exclude the packagers without it.
winget is reviewed by Microsoft: the first submission for a new publisher is checked by a person, not merged automatically.
Status on 2026-11-06: the tap exists and holds no casks yet. Torrenta and Termina have both packagers configured, waiting for the token. Mirada’s first winget submission (microsoft/winget-pkgs#471599) is open.
Signing
Section titled “Signing”- REL-15 MUST The macOS
.dmgis signed with the Developer ID Application certificate (team 8JKSF797L8), with the hardened runtime and per-app entitlements, notarized withnotarytool, stapled and checked withspctl; then the notarized app is launched once.- Check (code):
release.yml, or a script it runs, importsMACOS_CERT_P12andMACOS_CERT_PASSWORD, notarizes withAPPLE_API_KEY_P8,APPLE_API_KEY_IDandAPPLE_API_ISSUER, staples, runsspctland launches the app. - Reference: Editora’s “Import signing certificate (macOS)” and “Notarize DMG (macOS)” steps in
release.yml,packaging/macos/Editora.entitlements. All six apps sign, notarize, staple and runspctl; Editora, Termina, Mirada, Modula and nux then launch the notarized app. Torrenta does not yet: its “Smoke-test the packaged app” step launches the signed app before it is notarized, and its “Notarize the dmg (macOS)” step inrelease.ymlends atspctl. Mirada’s steps are inscripts/sign-mac.shandscripts/notarize-mac.sh.
- Check (code):
- REL-16 MUST Linux downloads are signed with the one shared OpenPGP release key (“Adrian De Leon (release
signing)”) in a job of their own, apart from the build legs (
sign-linuxin Editora):rpmsignfor the.rpm, a debsigs origin signature for the.deb, and an armored.ascbeside every file. The public key is committed aspackaging/linux/signing-key.ascand attached to each release.- Check (code): the release workflow has a job apart from the build legs, whatever it is called, that reads
the release key and its passphrase from the repository’s secrets (
LINUX_GPG_KEYandLINUX_GPG_PASSPHRASEin Editora), signs each.rpmand.deband writes an.ascbeside every Linux file; andpackaging/linux/signing-key.ascexists, and the release attaches that public key (aseditora-signing-key.ascin Editora). - Reference: Editora
scripts/release/sign-linux-packages.sh,scripts/release/check-linux-signatures.sh. Done in Editora, the app template, Torrenta, Termina, Mirada and Modula, all with the same key; nux has nosign-linuxjob and no committed key yet.
- Check (code): the release workflow has a job apart from the build legs, whatever it is called, that reads
the release key and its passphrase from the repository’s secrets (
- REL-17 SHOULD The Windows
.msiis signed with Authenticode, once the certificate is chosen.- Check (code): the Windows leg signs the
.msibefore it is uploaded. - Reference: no app signs one yet. The app template’s
release.ymlhas the step: once the repository holds a certificate (WINDOWS_CERT_PFX), it signs each.msiwithsigntoolbefore the upload. Open decision: SignPath Foundation (free for OSS), a Certum Open Source certificate, or Azure Trusted Signing. Until then MSIs are unsigned and SmartScreen warns.
- Check (code): the Windows leg signs the
- REL-18 MUST Every download has a GitHub build provenance attestation
(
actions/attest-build-provenance), whichgh attestation verifychecks.- Check (code): the release workflow has an
actions/attest-build-provenancestep whose subjects cover every file the release attaches. The test that keeps the two lists the same is QUAL-15’s. - Reference: Editora’s “Attest build provenance” step in
release.yml,ReleaseSupplyChainTest. Done in Editora, the app template, Termina and Mirada.
- Check (code): the release workflow has an
The certificate renews before 2027-11-30; the Apple membership before 2027-10-31.
CI/CD (GitHub Actions)
Section titled “CI/CD (GitHub Actions)”- REL-19 MUST The CI workflow (
ci.ymlin Editora) runs on every push to the default branch and every pull request, with two checks: the format check of PLAT-10 (spotless:check; the job Editora names Format) and the build with its tests (./mvnw verify, coverage gate included; Editora’s Build & Test), on the JDK PLAT-01 names. Both are required status checks for the default branch.- Check (code): the CI workflow triggers on
pushto the default branch and onpull_request. One of its jobs is the Format job of PLAT-10, which runsspotless:checkand neither builds nor tests, and its jobs between them run the whole suite andverifywith the coverage gate: one job that runs./mvnw verify, or, as in Editora, jobs that runtestin shards and one that runsverifyover their results. What the jobs are called is the app’s own. A workflow that lacks a trigger or one of the two checks fails the rule. That the default branch requires both is a repository setting, which no file shows. An audit run from the app’s checkout alone reports the rule asnot-checkedand says what would settle it. - Reference: Editora
ci.yml, onmaster(itsformatjob, its fourtestsshards and itsbuildjob, which runsverifyover the shards’ results); the app template’sci.ymland Termina’sci.yml, onmaster, and Mirada’sci.yml, onmain, each with a job forspotless:checkand one forverify. Torrenta (ci.yml), Modula (build.yml) and nux (ci.yml) don’t yet: none has a format check of its own. Torrenta’s and Modula’s one test job runs./mvnw verify, which their poms bindspotless:checkto, so a single status stands for both checks; nux’s pom has no Spotless, and its job runs./mvnw test, notverify. Modula’s and nux’s builds have no coverage gate either (PLAT-12). No file of any of them shows the required checks.
- Check (code): the CI workflow triggers on
- REL-20 MUST The tests run on all three OSes: the pure suite (no JavaFX toolkit) on Linux, macOS and
Windows, and the FX suite on Linux and at least one more. They run there every day or on every pull request. How
the runs are split is the app’s own: one workflow that runs everything on every pull request meets this, and so
does a quick workflow for pull requests with a fuller one on a schedule. A release waits for these runs on its own
commit, on all three OSes: that it waits at all is REL-30.
- Why: path separators, line endings, case-insensitive file systems and process spawning fail on one OS only, and the pure suite is where they show; the FX suite catches layout and focus differences. The FX suite is the slow one (three shards on macOS in Editora), so it is asked on two OSes and not three: the third is covered by the pure suite alone.
- Check (code): taken together, the workflows’ test jobs run the pure suite on
ubuntu-*,macos-*andwindows-*runners and the FX suite onubuntu-*and one more, under ascheduleor apull_requesttrigger that needs no label; and the tests a release waits for (REL-30) ran on those runners, in the release workflow itself or in the run it reads. - Reference: Editora splits them:
ci.ymlruns the whole suite on Linux on every pull request, andfull-tests.ymlthe pure suite on Windows and macOS and the FX suite on macOS, in three shards, daily, on a pull request labeledfull-ciand before every release: the “Check that the Full tests passed on this commit” step inrelease.yml. It lists flaky tests in the job summary (scripts/ci/ReportFlakes.java). The app template splits them the same way, and its release callsfull-tests.ymlitself. Termina (ci.yml), Torrenta (ci.yml), Mirada (ci.yml), Modula (build.yml) and nux (ci.yml) run the whole suite on the three OSes on every pull request.
- REL-21 MUST The release workflow (
release.ymlin Editora) runs on a version tag (v*meets it; the version-shapedv[0-9]+.[0-9]+.[0-9]+*is the better pattern, since a tag likevendor-importdoesn’t match it), withworkflow_dispatchas a dry run that builds and signs and publishes nothing. The tag matching the pom is REL-05, the tests it waits for REL-30, the release-asset check REL-07, and the bump to the next snapshot REL-06.- Check (code): the release workflow triggers on a tag pattern that starts with
vand onworkflow_dispatch. A dispatched run goes through the build and signing jobs and publishes nothing: the step that publishes runs in a mode that publishes nothing (JReleaser’s--dry-run), or the job that publishes runs only for a tag (anif:on the ref). - Reference: Editora
release.yml, whose “JReleaser” step takesrelease --dry-runon a dispatch; the template, Termina, Torrenta and Mirada pass JReleaser--dry-runthe same way. Modula’srelease.ymland nux’srelease.yml, which have no JReleaser, run their publishing job only for a tag (if: startsWith(github.ref, 'refs/tags/…')).
- Check (code): the release workflow triggers on a tag pattern that starts with
- REL-30 MUST A release is cut only from a commit whose tests passed: the release workflow runs the suite
before it builds the installers, or a preflight job reads CI’s result for the tagged commit and stops when it is
not green.
- Why: the build legs often skip the tests (
-DskipTests), and a tag can be pushed on any commit, so without this a release can be cut from code whose checks failed or never ran. - Check (code): in the release workflow, every job that publishes needs, directly or through the jobs between, a
job that settles the tests on the tagged commit: it runs them (a Maven run that reaches the
testphase,./mvnw test,package,verifyorinstall, with no-DskipTestsand no-Dmaven.test.skip, or a call to the full-tests workflow), or it reads the conclusion of the CI run onGITHUB_SHAand fails on anything but success. - Reference: both ways are in use, and all seven release workflows meet it. A preflight that reads CI: Editora’s
“Check that CI passed on this commit” step in
release.yml(scripts/release/CheckRelease.javaci, which waits up to 30 minutes for the required checks; its build legs run-DskipTests), and Torrenta’s “Require CI on this commit” step inrelease.yml, which reads the newestci.ymlrun on the commit and starts one when there is none. The suite in the release: the template’sfull-testsjob inrelease.ymlcallsfull-tests.ymlbeforebuild; the “Build, test and package” step of Termina’srelease.ymland Mirada’srelease.ymlruns./mvnw … verifyon every build leg; Modula’s “Build the installer” step inrelease.ymlrunspackagewith the tests; nux’s build legs run a “Test” step (./mvnw test) before they package, inrelease.yml. In each of the five the job that publishes needs the build legs, directly or through the signing and asset-check jobs. Mirada’scodecs.ymlalso creates a GitHub release, of the codec libraries its build downloads by checksum: that is a dependency, not a release of the app, and the app’s own release runs the suite with them.
- Why: the build legs often skip the tests (
- REL-22 MUST Every workflow pins each third-party action to a commit SHA, with its version in a comment
(
actions/setup-java@b843ebf… # v6.1.0).- Check (code): every
uses:in.github/workflows/, and in a composite action under.github/actions/where the repository has one, ends in a 40-character SHA and a comment naming its version (# v6.1.0,# 2.5.0,# v2), never a branch such as# main. Thev2in Editora’s and Torrenta’sjreleaser/release-action … # v2names that action’sv2line, whose head the SHA is; the template, Termina and Mirada pin its 2.5.0 release. - Command:
[ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; [ -d .github/workflows ] || { echo 'no .github/workflows'; exit 1; }; ! grep -rhE '^[[:space:]]*-?[[:space:]]*uses:' .github/workflows .github/actions 2>/dev/null | grep -vE 'uses:[[:space:]]*\./' | grep -vE '@[0-9a-f]{40}[[:space:]]+#[[:space:]]*v?[0-9]' - Reference: Editora
.github/workflows/.
- Check (code): every
- REL-23 MUST Dependabot updates
github-actionsandmavenweekly.- Check (code):
.github/dependabot.ymllists both ecosystems withinterval: weekly. - Reference: Editora
.github/dependabot.yml.
- Check (code):
- REL-24 MUST Every workflow starts from
permissions: contents: read, or from less; only a job that needs write access asks for it, in its own block.- Check (code): each workflow has a top-level
permissionsthat grants no write:contents: read, or less (permissions: {}); and everywritesits in a job’s ownpermissions. - Reference: Editora
release.yml:release(publish),bump(the pull request) andpreflight(start a Full tests run). Modula’snotify-catalog.ymlstarts frompermissions: {}.
- Check (code): each workflow has a top-level
- REL-25 SHOULD Every
actions/setup-javastep caches Maven’s repository (cache: maven). The JDK it sets up is PLAT-01’s.- Check (code): each
setup-javastep hascache: maven. - Reference: Mirada (
ci.yml), Modula, nux and the app template (ci.yml,full-tests.yml,release.yml), on every step. Editora (ci.yml,release.yml), Termina and Torrenta each have asetup-javastep without it. Editora sets up Temurin for its tests and Liberica for the release build, for linux-aarch64 coverage.
- Check (code): each
- REL-26 MUST Every job that runs steps has
timeout-minutes. A job that calls a reusable workflow (uses:in place ofsteps:) takes notimeout-minutes: GitHub does not accept the key there, and the called workflow’s own jobs carry theirs.- Check (code): in every workflow, every job with
steps:setstimeout-minuteson the job itself; a timeout on one of its steps does not stand for it. A job withuses:and nosteps:is not judged. - Reference: every job of Editora’s five workflows (
ci.yml,full-tests.yml,release.ymland the rest), of the template’s three, Termina’s two and Mirada’s five sets one; the template’sfull-testsjob inrelease.yml, which callsfull-tests.yml, carries none, as the rule says, and nor does thewingetjob of Mirada’srelease.yml, which callswinget.yml. Torrenta, Modula and nux don’t yet: the two jobs of Torrenta’sci.ymland the one of itsengine-soak.ymlset none (itsrelease.ymldoes); no job in Modula’s three workflows (build.yml,release.yml,notify-catalog.yml) or in nux’s two (ci.yml,release.yml) sets one: each app has it on one step only, the one that notarizes.
- Check (code): in every workflow, every job with
- REL-31 MUST Every workflow that runs on pull requests has a
concurrencygroup that cancels a superseded pull-request run, and never a run on the default branch.- Check (code): every workflow with a
pull_requesttrigger has aconcurrencyblock whosegroupis shared by the runs of one pull request and by no run on the default branch (keyed bygithub.ref, or by the pull request’s number), and whosecancel-in-progressis true for a pull-request run: true, or an expression that is true there. And in that workflowcancel-in-progressis never true for a run on the default branch, whatever starts it (a push, a schedule, or a run started by hand, whichworkflow_dispatchallows on any branch): it is an expression that is false there, and it may be plain true only in a workflow that nothing can start on the default branch. A workflow with nopull_requesttrigger is not judged. - Reference: Editora
ci.ymlandfull-tests.yml(cancel-in-progress: ${{ github.event_name == 'pull_request' }}, in a group keyed by the pull request’s number). The template’s (ci.yml,full-tests.yml), Termina’s (ci.yml) and Mirada’s (ci.yml) pull-request workflows use the same expression, Termina’s and Mirada’s in a group keyed bygithub.ref. Editora’s third pull-request workflow,terminal-image.yml, doesn’t yet: itscancel-in-progressis plain true, and beside pull requests and pushes toprobe/**it can be started by hand, so a second run started onmastercancels the first. Torrenta, Modula and nux don’t either: Modula’sbuild.ymland nux’sci.ymlrun on pull requests with noconcurrencyblock, so they cancel nothing, and Torrenta’sci.ymlsetscancel-in-progress: truefor its pushes tomasteras well.
- Check (code): every workflow with a
- REL-27 MUST A CI run leaves its results where they can be read without running it again: it uploads the
surefire reports even when tests fail, uploads the JaCoCo report, and writes the coverage totals to the job
summary.
- Check (code): the step that uploads the surefire reports runs under
if: always(), a step uploads the JaCoCo report, and a step appends the coverage totals to$GITHUB_STEP_SUMMARY. - Reference: Editora’s “Upload test reports and coverage data” and “Summarise coverage” steps in
ci.yml.
- Check (code): the step that uploads the surefire reports runs under
- REL-28 MUST Signing skips cleanly when the secrets are absent (forks, dry runs), so they still build; a tag
without them fails.
- Check (code): each signing step checks its secrets first, skips without them, and fails on a tag push.
- Reference: Editora’s “Import signing certificate (macOS)” step in
release.ymlchecksMACOS_CERT_P12first.
- REL-29 MUST The packaged app is launched once on each OS before a release (a smoke test).
- Check (code): the release workflow runs the packaged launcher on each OS (a Linux, a macOS and a Windows leg) before the step that publishes.
- Reference: Torrenta’s “Smoke-test the packaged app” step in
release.ymlruns the launcher in the image of each of its three targets, one per OS. Editora runs only the notarized macOS app (--version,--check-terminal).
Pauta 6.1.0 · · Changelog · Permanent link to this page in 6.1.0