Skip to content

Releases & Versioning

How Vista Platform Core releases are versioned, what they contain, and how to verify them.

Versioning

Releases follow Semantic Versioning (vMAJOR.MINOR.PATCH). For any given release the version is identical across:

  • the git tag (e.g. v0.2.0),
  • the Helm chart version and appVersion, and
  • every service container image tag.

So a chart at 0.2.0 always runs the v0.2.0 images — there is no skew to reason about.

What a release contains

Each release is published as signed, attested artifacts on GHCR:

  • The Helm chart — oci://ghcr.io/vistasecurity/vistaplatform:<version>. Built from this source, unobfuscated.
  • Service images — ghcr.io/vistasecurity/<service>:<version>, each cosign-signed (keyless OIDC). Each image also carries two build attestations that BuildKit generates while building it: an SPDX software bill of materials and SLSA build provenance in its most detailed form (mode=max). They are stored in the image index next to the image, not as separate cosign attestations; see Inspect an image's SBOM and provenance.
  • Sensor and device-agent binaries — prebuilt for multiple OSes and architectures, attached to the GitHub Release along with a signed SHA256SUMS.

Install and upgrade from the published OCI chart, never from the repository.

Release notes

  • Changelog: CHANGELOG.md at the repo root carries a section per version (Keep a Changelog format).
  • GitHub Releases: every release is published on the repository it was built from, with the changelog section as its notes. This is generated automatically by the release pipeline, so it never drifts from the changelog.

Verify a release

Signing is keyless: there is no key to trust, because the signing identity is the release workflow. That means the registry and the identity both depend on which edition you installed — so rather than guessing, use the command helm install printed at the end of its output. The chart fills in the registry, the version and the signing identity for the artifact you actually have.

For Core, that command is:

cosign verify ghcr.io/vistasecurity/vistaplatform:<chart-version> \
  --certificate-identity-regexp '^https://github\.com/VistaSecurity/VistaPlatform-Core/\.github/workflows/release-core\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9.]+)?$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Substitute a service image ref (e.g. ghcr.io/vistasecurity/auth-service:<version>) to verify an image with the same identity.

Inspect an image's SBOM and provenance

The SBOM and provenance travel inside the image index that the cosign signature covers, so verify the image first, then read them with Docker Buildx:

# SPDX software bill of materials
docker buildx imagetools inspect ghcr.io/vistasecurity/auth-service:<version> \
  --format '{{ json .SBOM }}'

# SLSA build provenance (source, build arguments, base images)
docker buildx imagetools inspect ghcr.io/vistasecurity/auth-service:<version> \
  --format '{{ json .Provenance }}'

These are not cosign attestations, so cosign verify-attestation does not find them. The Helm chart carries a cosign signature but no SBOM or provenance.

Upgrading

The usual way is the admin console: Maintenance → Backups to take a backup, then Maintenance → About & Updates to see what's new and update. See Maintenance in the admin console. The manual procedure below is for installs managed by Argo CD or Flux and the fallback.

See INSTALL.md's "Run it" section for cross-version upgrade mechanics (--reset-then-reuse-values, schema-migration/seed Jobs, single-node surge caveats). The chart's NOTES.txt echoes the key upgrade flags on every helm upgrade.

Bundled NATS server: 2.10 to 2.14

This release upgrades the NATS server bundled with the chart (datastores.nats) from 2.10, which the NATS project no longer patches, to 2.14.

  • JetStream data is preserved. Streams, durable consumers, their acknowledgement state and stored messages are read in place from the existing volume. Nothing needs to be re-created.
  • Rolling the chart back is not clean. If you later roll back to a release that ships NATS 2.10, the server rebuilds the stream index on its first start and logs Filestore [<stream>] Recovering stream state from index errored: corrupt state file. The messages and consumer state were intact in testing, but the rebuild is expected, not a fault.
  • Take a backup of the NATS volume before upgrading if you need a clean rollback. The bundled server stores its data on the PVC named nats-data-nats-0; snapshot it with your CSI driver or storage layer.
  • A pinned tag keeps the old server. If your values file sets datastores.nats.image.tag, that value wins over the chart default, so remove it (or set it to 2.14-alpine) to take this change. Use --reset-then-reuse-values as described above. If you run an external NATS (datastores.nats.enabled: false), nothing changes for you; keep it on a release line the NATS project still patches.

1.0.0 is a fresh install only — there is no upgrade path from a core-v0.x release. See INSTALL.md's "Run it" section and the "Breaking / Upgrading" notes under [1.0.0] in CHANGELOG.md before upgrading an existing deployment: the port-as-asset tables were dropped rather than migrated, and credential encryption moved to v2, so credentials need re-entering and sensors re-enrolling on the first 1.0.0 deploy.

Where documentation lives

  • Tenant-facing capabilities: docsv4/core/
  • Deployment and operations: docsv4/core/operate/