FrameWorks GitOps

Release manifests, cluster configuration, and infrastructure secrets for the FrameWorks platform. Consumed by the FrameWorks CLI for deployments.

Architecture manifests are plaintext — anyone can see exactly how FrameWorks is deployed. Server IPs and credentials are SOPS-encrypted with age.

Structure

.
├── releases/                          # Release manifests (CI-generated, one per version tag)
│   ├── v0.1.0-rc1.yaml
│   └── ...
├── channels/                          # Channel pointers
│   ├── stable.yaml                    # Latest production-ready release
│   └── rc.yaml                        # Latest release candidate
├── clusters/                          # Cluster configuration
│   └── production/
│       ├── cluster.yaml               # Architecture manifest (plaintext)
│       ├── edge.yaml                  # Edge node topology (plaintext)
│       └── hosts.enc.yaml             # Host IPs + SSH targets (SOPS-encrypted)
├── secrets/
│   └── production.env                 # Credentials (SOPS-encrypted)
└── .sops.yaml                         # SOPS encryption configuration

Cluster Manifests

clusters/production/cluster.yaml is the full deployment topology: every service, database, message broker, and cache — how they're connected, what hosts they run on, and how they're configured. This is published in plaintext for full transparency.

What's not in the plaintext manifest:

• Server IP addresses → hosts.enc.yaml (SOPS-encrypted)
• SSH credentials → hosts.enc.yaml (SOPS-encrypted)
• API keys, passwords, tokens → secrets/production.env (SOPS-encrypted)

Decrypting

# View host IPs
sops -d clusters/production/hosts.enc.yaml

# View/edit secrets
sops secrets/production.env

Requires the age private key at ~/.config/sops/age/keys.txt (or set SOPS_AGE_KEY_FILE).

Provisioning

# From local checkout
frameworks cluster provision --manifest clusters/production/cluster.yaml --age-key ~/.config/sops/age/keys.txt

# From GitHub (fetches manifest + encrypted files, decrypts automatically)
frameworks cluster provision --repo org/gitops --age-key ~/.config/sops/age/keys.txt

Release Manifests

Automatically generated by CI when a version tag is pushed to the monorepo. Each manifest contains:

• Platform version, git commit SHA, timestamp
• Docker image references with SHA256 digests
• Native binary download references
• Tested infrastructure versions

Channels

• stable — Latest production-ready release. Production clusters track this.
• rc — Release candidate. Staging clusters track this.

Release Flow

1. Tag: Create vX.Y.Z (GA) or vX.Y.Z-rcN (RC) in the monorepo.
2. Build: CI builds all services, pushes images, compiles native binaries.
3. Manifest: CI generates releases/<tag>.yaml and pushes here.
4. Channel: RC tags update channels/rc.yaml. GA tags update channels/stable.yaml.
5. Deploy: The CLI reads the manifest to pull images by digest and download binaries.

Secrets Management

Secrets are encrypted at rest using SOPS with age keys. SOPS encrypts values while leaving keys/structure visible — this is by design for transparency.

Pre-commit hooks prevent:

• Committing unencrypted secret files
• Leaking IP addresses into plaintext manifests
• Accidentally committing age private keys

See docs/key-rotation.md for rotation procedures.