Quick start

Install Trial, open the console, run one real server-mode gate.

The normal path is server mode: install the self-hosted package, create a scoped token, connect one source, then run releasepassport gate from CI. Local mode is only for developer smoke.

Before you start

You need

A Kubernetes cluster where the customer runtime can be installed.

A public/internal customer-owned domain, or local port-forward mode when evaluating without DNS.

No external auth provider is required for the first install; basic auth is built in. OIDC/proxy auth is optional.

A CI/CD secret store that can hold RELEASEPASSPORT_TOKEN.

One scoped evidence source to start, ideally Kubernetes readiness or CI metadata.

Do not start with

Cluster-admin credentials for every namespace.

All Prometheus queries or full organization-wide metrics access.

Production enforce mode on day one.

Arconath-specific domains, SOPS keys, Keycloak realm, or internal namespace values.

Install the Trial self-hosted package.

Sign in to the Release Passport Portal, generate a Trial install token, then run the token-first installer. The installer chooses Kubernetes or Docker Compose, uses customer storage env vars when present, and prints the customer-owned console/API URL when ready.

Install

# Sign in to https://releasepassport.com/portal first.
# Customer runtime images are pulled only from the official Release Passport registry.
# The installer creates or preserves RELEASEPASSPORT_INSTALL_ID in the runtime Secret.
curl -fsSL https://releasepassport.com/install.sh | bash -s -- \
  --install-token <portal-install-token>

Open the customer console.

Open https://release-passport.example.com/console. The console explains decisions after a gate runs. It is not a replacement for CI/CD and it should not be the only place where release blocking happens.

Create a scoped pipeline token.

Create a gate token in the customer secret store. Store the same value in CI secrets as RELEASEPASSPORT_TOKEN.

Token

RELEASEPASSPORT_TOKEN="$(openssl rand -hex 32)"
kubectl -n releasepassport create secret generic releasepassport-runtime \
  --from-literal=RELEASEPASSPORT_GATE_TOKEN="$RELEASEPASSPORT_TOKEN" \
  --dry-run=client -o yaml | kubectl apply -f -

kubectl -n releasepassport rollout restart deploy/releasepassport-api deploy/releasepassport-worker

Connect one scoped evidence source.

Start with one source such as Kubernetes namespace readiness, Prometheus query allowlist, GitOps app health, CI/CD metadata, or error tracking project. The goal is high-quality evidence for one service, not broad automatic scraping across every app.

Run the gate before promotion.

Start in shadow mode. The command writes a passport and returns a verdict without blocking unless the selected fail threshold is reached.

CI gate

releasepassport gate \
  --api-url https://release-passport.example.com/releasepassport/v1 \
  --token "$RELEASEPASSPORT_TOKEN" \
  --mode shadow \
  --service checkout-api \
  --environment production \
  --namespace apps-checkout \
  --source-sha "$GITHUB_SHA" \
  --artifact "$IMAGE_DIGEST" \
  --release-id "$GITHUB_RUN_ID" \
  --fail-on block

Inspect the passport.

Open Passports in the console to review verdict, blockers, runtime health, rollback readiness, policy reasons, and evidence timeline.

How to know the quick start worked

CheckConsole opens

Expected resultThe user reaches /console after OIDC login.

If it failsFix OIDC issuer, client, callback URI, cookie domain, or allowed group mapping.

CheckGate command exits

Expected resultThe command prints a passport ID, verdict, risk, and summary.

If it failsCheck token, API URL, service name, source SHA, artifact digest, and TLS.

CheckPassport appears

Expected resultPassports list includes the release ID from CI.

If it failsVerify the API accepted the gate request and workspace/service scope matches.

CheckEvidence is fresh

Expected resultConnector freshness is green or recently observed.

If it failsCheck connector token, namespace/project scope, query allowlist, and worker logs.

CheckMode is shadow

Expected resultThe first result records evidence without unexpectedly blocking deploys.

If it failsConfirm --mode shadow and default runtime mode in Helm values.

Check	Expected result	If it fails
Console opens	The user reaches /console after OIDC login.	Fix OIDC issuer, client, callback URI, cookie domain, or allowed group mapping.
Gate command exits	The command prints a passport ID, verdict, risk, and summary.	Check token, API URL, service name, source SHA, artifact digest, and TLS.
Passport appears	Passports list includes the release ID from CI.	Verify the API accepted the gate request and workspace/service scope matches.
Evidence is fresh	Connector freshness is green or recently observed.	Check connector token, namespace/project scope, query allowlist, and worker logs.
Mode is shadow	The first result records evidence without unexpectedly blocking deploys.	Confirm --mode shadow and default runtime mode in Helm values.