Releases

Cutting a release

1. Make sure CI on main is green.
2. Tag and push: git tag v1.2.3 && git push origin v1.2.3.

The release workflow builds every artifact, tests the Linux packages and the Windows MSI by installing and removing them, and publishes:

• A GitHub release with all artifacts, a SHA256SUMS file signed keylessly with Sigstore (SHA256SUMS.sigstore.json), and build provenance attestations.
• Container images ghcr.io/<owner>/yarma-api, yarma-license-center and yarma-web, tagged with the version. Each image is signed with cosign and carries an SBOM and provenance.

Run the workflow by hand (Actions → release → Run workflow) for a dry run. It builds everything and keeps the results as workflow artifacts, without publishing anything. Options of a manual run:

• version: X.Y.Z, or a pre-release such as 0.1.0-alpha.1. Pre-releases are marked as such on GitHub; .deb/.rpm write them as 0.1.0~alpha.1 so they sort before 0.1.0, and the MSI carries the numeric part (0.1.0) and upgrades over the same numeric version.
• components: agents builds only the agent packages (Linux, Windows, macOS) and the server binaries, skipping the desktop console and container images — a fraction of the runner minutes (macOS minutes count tenfold on private repositories).
• publish: tags the commit v<version> and publishes the GitHub release. Its signed checksums then name refs/heads/main instead of a tag in the certificate identity.

Verify a download:

cosign verify-blob SHA256SUMS --bundle SHA256SUMS.sigstore.json \
  --certificate-identity-regexp 'https://github.com/javadmohebbi/YARMA/.github/workflows/release.yml@refs/tags/v.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
sha256sum --ignore-missing -c SHA256SUMS
gh attestation verify yarma-agent_1.2.3_amd64.deb --repo javadmohebbi/YARMA

Building agents without GitHub Actions

scripts/build-agent-linux.sh VERSION amd64|arm64 OUT builds the Linux agent in a container (Ubuntu 22.04 baseline; arm64 is cross-compiled with the PipeWire libraries for the screen sharing helper), then scripts/package-linux.sh VERSION OUT DIST ARCH packages it. The release workflow's linux-agent-arm64 job uses the same script. Windows and macOS packages need their own runners.

Website documentation

https://yarma.avadeja.com/docs/ is generated from the guides in docs/ by website/scripts/build-docs.mjs on every website build (npm run build), stamped with the release version (YARMA_VERSION, else the latest git tag). Publishing a release therefore means rebuilding the website from the release commit and deploying the License Center bundle: the docs always match the downloadable version. Pages and their order are listed in SECTIONS in that script.

Code signing (optional)

Without these repository secrets, artifacts are built unsigned. Windows SmartScreen warns on unsigned installers, and macOS Gatekeeper blocks unsigned packages unless the user allows them.

Shipping unsigned

Releases work without any of these secrets. What changes per platform:

Self-signed Windows certificate (managed fleets)

A self-signed certificate removes the SmartScreen and UAC "unknown publisher" warnings on machines that trust it; on any other machine it behaves like unsigned. It does not help on macOS: Gatekeeper accepts only Apple Developer ID certificates.

1. On a Windows machine, run .\scripts\selfsign-windows.ps1 (options: -Subject, -Years (default 3), -OutDir). It writes yarma-codesign.pfx, the public yarma-codesign.cer and secrets.txt, and removes the key from the certificate store.
2. Add the two values from secrets.txt as the WINDOWS_CERT_PFX and WINDOWS_CERT_PASSWORD repository secrets, then delete the .pfx and secrets.txt.
3. Distribute yarma-codesign.cer to the Trusted Root Certification Authorities and Trusted Publishers stores of the target machines:
   • GPO: Computer Configuration → Policies → Windows Settings → Security Settings → Public Key Policies → import into both stores.
   • Intune: a Trusted certificate profile for the Root store, plus a PowerShell platform script running the TrustedPublisher import below.
   • One machine (elevated PowerShell):

     Import-Certificate -FilePath yarma-codesign.cer -CertStoreLocation Cert:\LocalMachine\Root
     Import-Certificate -FilePath yarma-codesign.cer -CertStoreLocation Cert:\LocalMachine\TrustedPublisher
     

4. Check a signed build: Get-AuthenticodeSignature .\yarma-agent.msi reports Valid on a machine that trusts the certificate.

Trusting a root certificate lets its key sign anything for those machines: keep the .pfx only in the repository secrets and rotate it (rerun the script, update both secrets and the distributed .cer) before it expires or if it leaks. Moving to a commercial OV/EV certificate later needs only the two secrets changed.

Installing

• Server: quick start, single host, Kubernetes.
• Agents on Windows, macOS and Linux, including mass deployment, upgrade and uninstall: agents.

Documentation for Yarma 0.1.0-alpha.4. Something unclear? Ask us.