Why we built Project Promotion CD

SAMSKARA has had Git Integration for a while: connect a project to a repo, push, pull, review a diff, done. It’s the right tool for the question “what am I working on, and can I get it into version control the way I already work.” It is the wrong tool for a different question: “how does a change actually get into production.”

Those sound like the same problem. They aren’t.

Two different questions, two different answers

Git Integration is interactive by design — a person clicks Push, reviews what changed, clicks Confirm. That’s exactly what you want while you’re building something. It’s exactly what you don’t want as the only path into a production environment, because it means production changes require someone to be sitting at a keyboard with push access to that environment, every time.

The answer wasn’t to make Git Integration more automated. It was to build a second, deliberately separate mechanism — Project Promotion CD — that answers a narrower question: given a commit a CI pipeline has already checked out and reviewed, can it be applied to production safely, automatically, with no human clicking anything?

What actually moves, and how it authenticates

A promotion is authenticated by a Promotion Service Token — scoped to specific projects, revocable, never a general-purpose credential, and never resolving to a human user the way a personal login does. If a project isn’t on a token’s allow-list, that token can’t touch it. Revoking one is immediate.

The pipeline doesn’t hand SAMSKARA a repo URL and a commit hash and ask it to go fetch something. It sends the exact file contents it already checked out in the request body, plus the commit SHA, plus a server-computed checksum for the audit trail. SAMSKARA never independently reaches out to GitHub during a promotion. That’s not a minor implementation detail — it’s the whole point. Whatever CI checked out and validated is exactly, byte-for-byte, what gets applied. There’s no gap where a different version could get substituted in transit.

Validation that actually blocks

Before anything gets applied, SAMSKARA checks whether every named dependency the incoming notebooks reference — a database connection, a secret, a storage profile — already exists in the target environment. Three outcomes: PASS, WARN, or BLOCK. A BLOCK doesn’t get logged and skipped. It comes back as a real, non-2xx HTTP response, specifically so a CI job sees a failure and stops — never a quietly-successful deploy sitting on top of a missing dependency.

We built this on top of validation logic that already existed for a related, smaller feature (promoting a single notebook between two environments inside one deployment). Reusing it meant the same “resources don’t get auto-created, ever” guarantee applies here too — a promotion will tell you exactly what’s missing in the target, but it will never quietly create it for you.

Turning Git Integration off in production, safely

Once Project Promotion CD existed, the obvious next step was letting an org actually rely on it: an admin-only toggle to disable interactive Git push/pull in production entirely, so changes there can only arrive through the approved pipeline. It sits underneath a deployment-level override that always wins — so an operator can lock things down at the infrastructure level regardless of what any admin setting says, and just as easily hand day-to-day control back to an org admin without needing a server restart.

The build → review → promote → validate → run path

Put together, this gives SAMSKARA the same shape most teams already expect from application code, applied to notebooks and pipelines instead: work in Git, review the diff, let CI check it out and send it forward, validate it against the real target before anything lands, and only then does it run. None of that requires a human with production credentials to personally execute the last step.

That’s the part we actually wanted — not automation for its own sake, but a production path that doesn’t depend on someone remembering to be careful.