Nojam documentation

How to install and run Nojam, set up Vault for it, move from one shared state to one per namespace, and check its security.

This guide is published with the first public release. Pilot customers get the full guide now, with the source repository.

Start here

Install Nojam for a pilot: The host, the GitHub App, the Vault role, the runner image and the checks to run before production.
Your first pull request: A stack in runner.yaml, a plan on the pull request, an approval and an apply, end to end.

Stacks and targets: How a repository declares stacks, how each stack maps to targets such as dev, uat and production regions, and how they are discovered.
Plans and approvals: What is planned on a pull request, who may approve, how approval binds to the plan, and when a merge needs approval again.
Vault credentials for jobs: How a job logs in to Vault, the sealed hand-over, read-only plan roles, apply roles bound to main, and revocation.
Deployments and rollback: Promotion order, canary regions, all-or-nothing deployments, and what rollback restores and what it cannot.

Vault setup: What Nojam needs on each cluster: the JWT auth mount, the roles, the policies and the issuer, with a platform stack in Terraform.
Namespaces and vending: One namespace per team on Vault Enterprise, and creating a team namespace from one line in teams.yaml.
Splitting a shared state: Moving from one shared state to one per namespace with nojam state split, proven with zero-diff plans before anything applies.
Protection rules: The built-in baseline, break-glass, critical mounts, grants across namespaces and your own rules by Vault path.
Providers and modules: The provider mirror, the allow-list, lock files, provider changes on the pull request, and module pinning.

Configuration reference: Every server and runner setting, runner.yaml, sign-in, ServiceNow, OPA, audit anchoring and compliance streaming.
Pipeline steps: Your own checks after every plan, declared once by the platform team, that a pull request cannot drop.
High availability: Several replicas on PostgreSQL, leader election, durable webhooks and fenced runner attempts.
Alerts: The Prometheus alert rules and the runbook for each one.
Backup and restore: What to back up, how to restore, and the restore drill.
Retention: What Nojam keeps and for how long: webhook payloads, plan files, job logs and the audit log.
Support bundle: What to send when something is stuck, and what is never in it.

Threat model: What Nojam protects, the actors and trust boundaries, the threats and controls, and the open items.
Cryptographic inventory: The keys Nojam holds and the algorithms it uses.
Security testing: The checks on every change, the fix time frames, and how findings are handled.
Verifying a release: Checking cosign signatures, SBOMs and SLSA provenance before you install.