This document outlines the release process for NVIDIA Eidos. For contribution guidelines, see CONTRIBUTING.md.

• Repository admin access with write permissions
• Understanding of semantic versioning (vMAJOR.MINOR.PATCH)
• Access to GitHub Actions workflows

For standard releases from the main branch.

Steps:

1. Ensure main is ready:

   git checkout main
   git pull origin main
   make qualify  # All checks must pass

2. Create and push a version tag:

   git tag v1.2.3
   git push origin v1.2.3

3. Automatic workflows trigger (via on-tag.yaml):

   • Go CI validates code quality (tests, lint)
   • GoReleaser builds binaries and container images
   • SBOM generation for all artifacts
   • Attestations signed with Sigstore
   • GitHub Release created with changelog
   • Cloud Run deployment (eidosd API server)

4. Verify artifacts (see Verification below)

For convenience, use Makefile targets:

make bump-patch   # v1.2.3 → v1.2.4
make bump-minor   # v1.2.3 → v1.3.0
make bump-major   # v1.2.3 → v2.0.0

These create and push the tag automatically.

For rebuilding from existing tags or emergency releases:

1. Navigate to Actions → On Tag Release
2. Click Run workflow
3. Enter the existing tag (e.g., v1.2.3)
4. Click Run workflow

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ Tag Push │───▶│  Go CI   │───▶│  Build   │───▶│  Attest  │───▶│  Deploy  │
└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
                  tests +         binaries +      SBOM +          Cloud Run
                  lint            images          provenance      (eidosd)

Built via GoReleaser for multiple platforms:

Published to GitHub Container Registry (ghcr.io/nvidia/):

Tags: latest, v1.2.3

Every release includes:

• SLSA Build Level 3 Provenance: Verifiable build attestations
• SBOM: Software Bill of Materials (SPDX format)
• Sigstore Signatures: Keyless signing via Fulcio + Rekor
• Checksums: SHA256 checksums for all binaries

All releases must pass:

• Unit tests: With race detector enabled
• Linting: golangci-lint + yamllint
• License headers: All source files verified
• Security scan: Trivy vulnerability scan

# Get latest release tag
export TAG=$(curl -s https://api.github.com/repos/NVIDIA/eidos/releases/latest | jq -r '.tag_name')

# Verify with GitHub CLI (recommended)
gh attestation verify oci://ghcr.io/nvidia/eidos:${TAG} --owner nvidia
gh attestation verify oci://ghcr.io/nvidia/eidosd:${TAG} --owner nvidia

# Verify with Cosign
cosign verify-attestation \
  --type spdxjson \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp 'https://github.com/NVIDIA/eidos/.github/workflows/.*' \
  ghcr.io/nvidia/eidos:${TAG}

# Download checksums file from GitHub Release
curl -sL "https://github.com/NVIDIA/eidos/releases/download/${TAG}/eidos_checksums.txt" -o checksums.txt

# Verify downloaded binary
sha256sum -c checksums.txt --ignore-missing

# Pull container images
docker pull ghcr.io/nvidia/eidos:${TAG}
docker pull ghcr.io/nvidia/eidosd:${TAG}

# Test CLI
docker run --rm ghcr.io/nvidia/eidos:${TAG} --version

# Test API server
docker run --rm -p 8080:8080 ghcr.io/nvidia/eidosd:${TAG} &
curl http://localhost:8080/health

• Semantic versioning: vMAJOR.MINOR.PATCH
• Pre-releases: v1.2.3-rc1, v1.2.3-beta1 (automatically marked in GitHub)
• Breaking changes: Increment MAJOR version

The eidosd API server is automatically deployed to Google Cloud Run on successful release:

• Project: eidosx
• Region: us-west1
• Service: api
• Authentication: Workload Identity Federation (keyless)

Deployment only occurs if the build step succeeds.

1. Check Actions → On Tag Release for error logs
2. Common issues:
   • Tests failing: Fix and create new tag
   • Lint errors: Run make lint locally first
   • Image push failures: Check GHCR permissions

Use manual workflow trigger with the existing tag. No need to delete and recreate tags.

# List revisions
gcloud run revisions list --service=api --region=us-west1 --project=eidosx

# Rollback to previous revision
gcloud run services update-traffic api \
  --to-revisions=api-PREVIOUS_REVISION=100 \
  --region=us-west1 \
  --project=eidosx

For urgent fixes:

1. Fix in main first:

   git checkout main
   git checkout -b fix/critical-issue
   # Apply fix, create PR to main, merge

2. Create hotfix release:

   git checkout main
   git pull origin main
   git tag v1.2.4
   git push origin v1.2.4  # Triggers automatic release

3. For patching older releases (rare):

   git checkout v1.2.3
   git checkout -b hotfix/v1.2.4
   git cherry-pick <commit-hash-from-main>
   git tag v1.2.4
   git push origin v1.2.4

Before creating a release tag:

• All CI checks pass on main (make qualify)
• CHANGELOG or release notes prepared (auto-generated from commits)
• Breaking changes documented
• Version follows semantic versioning
• No uncommitted changes

After release:

• GitHub Release created with changelog
• Container images available in GHCR
• Attestations verifiable
• Cloud Run deployment successful
• Announce release (if applicable)