Quickstart

Eight labs, one per combination of encryption mode and CI mode. Pick the pair that matches your situation and follow it end to end.

Configuring CodeSeal is answering two independent questions. Every lab here is one pair of answers, followed from an empty repository to a green build.

The two questions

What is the decryption material? — the encryption mode, chosen at sgit init, and about your team rather than your pipeline.


R · `recipient`	Every developer has their own keypair. Each file's key is wrapped to each person, so adding or removing someone is a rewrap rather than a shared-secret rotation.
P · `passphrase`	One shared secret, stretched with scrypt. Simple, and everyone who has it has everything.

Who holds it, who builds, and who starts the build? — the CI mode.


D · `portal-dispatch`	You hold the keys. `sgit push` triggers the build and sends the key material, sealed, with it.
S · `secrets`	GitHub Secrets holds the key material, permanently. GitHub triggers on push.
K · `portal-key`	A Portal holds it and hands it to the runner for one build. GitHub triggers on push.
B · `portal-build`	A Portal holds it and does the build. GitHub never sees plaintext.

Two axes, and they are genuinely independent: eight working combinations.

Each pair has a two-letter name, and sgit takes it as a command:

terminal

sgit rd        # = sgit init --mode recipient --ci-mode portal-dispatch

The letters are the two answers — Recipient or Passphrase, then Dispatch, Secrets, portal-Key or portal-Build. Every lab below gives the shorthand and the long form; sgit --help lists all eight.

Pick your lab

RD · Recipient + Dispatch

Recommended. Keys on your machine, builds on GitHub, triggered by sgit push. No long-lived decryption key anywhere on GitHub, and no Portal to run. ~15 minutes.

PD · Passphrase + Dispatch

The same trigger model with one shared secret instead of per-developer keys. Simplest thing that keeps decryption material off GitHub.

RS · Recipient + Secrets

Per-developer keys, with a CI runner key parked in GitHub Secrets. Ordinary on: push CI — nothing to run locally.

PS · Passphrase + Secrets

One shared passphrase in GitHub Secrets. The least moving parts of the eight, and the most trust placed in GitHub.

RK · Recipient + Portal Key

A Portal you run holds the keys and lends one to the runner for a single build. Central audit, builds still on GitHub.

PK · Passphrase + Portal Key

The same, with a shared passphrase as the material the Portal hands out.

RB · Recipient + Portal Build

The Portal decrypts and builds. GitHub is reduced to a trigger and a checkmark, and never sees a plaintext file.

PB · Passphrase + Portal Build

Portal-side builds with a shared passphrase.

Which one is yours

If…	Lab
You want the strongest default and are willing to trigger builds yourself	RD
You are one person, and per-developer keys are ceremony you do not need	PD
Builds must start on their own, with nothing running locally	RS or PS
You already run a Portal and want central audit	RK or PK
Your CI provider is explicitly outside the trust boundary	RB or PB

What every lab assumes

sgit on your PATH — see Install
git, and a repository you can push to
$CODESEAL set, or the default ~/Dev/config/codeseal
a fine-grained GitHub token — step 1 of every lab

Nothing else. No Docker, no Node, no Portal unless the lab's name says Portal.