CLI

Use server mode in pipelines. Use local mode only for dev smoke.

The CLI is the pipeline checkpoint. It sends release identity and evidence to the API, waits for a passport verdict, then exits according to the configured mode and fail threshold.

Normal path

Server mode.

releasepassport 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

Dev only

Local mode.

Local mode does not provide the core product value by itself because it cannot read customer runtime evidence from the self-hosted API and connectors.

local smoke

releasepassport gate --local --mode shadow \
  --service checkout-api \
  --environment dev \
  --source-sha "$(git rev-parse HEAD)" \
  --release-id local-smoke

Exit codes and modes.

shadow: records verdicts; exits 0 unless --fail-on threshold is met.

advisory: warns operators and creates audit evidence.

enforce: exits non-zero for configured HOLD or BLOCK thresholds.

--fail-on block is the safest first CI setting.

Common flags

Flag--api-url

RequiredServer mode

MeaningCustomer self-hosted API origin plus /releasepassport/v1. This is the normal CI path.

Flag--token

RequiredServer mode

MeaningBearer gate token from CI secret storage. Do not print it in logs.

Flag--local

RequiredDev only

MeaningRuns a local smoke decision without self-hosted connector evidence. Useful for trying syntax, not production value.

Flag--mode

RequiredYes

Meaningshadow, advisory, or enforce. Start shadow for new services.

Flag--service

RequiredYes

MeaningStable service identifier used by policies, connectors, reports, and passports.

Flag--environment

RequiredYes

MeaningTarget environment such as staging or production.

Flag--namespace

RequiredKubernetes scope

MeaningNamespace or runtime scope used by Kubernetes and GitOps evidence.

Flag--source-sha

RequiredYes

MeaningCommit SHA for release identity and audit traceability.

Flag--artifact

RequiredRecommended

MeaningImage digest or artifact identifier. Prefer immutable digests over tags.

Flag--release-id

RequiredRecommended

MeaningCI run, pipeline, deployment, or change request identifier.

Flag--fail-on

RequiredRecommended

MeaningWhich verdict causes non-zero exit, commonly block first, then hold when ready.

Flag	Required	Meaning
--api-url	Server mode	Customer self-hosted API origin plus /releasepassport/v1. This is the normal CI path.
--token	Server mode	Bearer gate token from CI secret storage. Do not print it in logs.
--local	Dev only	Runs a local smoke decision without self-hosted connector evidence. Useful for trying syntax, not production value.
--mode	Yes	shadow, advisory, or enforce. Start shadow for new services.
--service	Yes	Stable service identifier used by policies, connectors, reports, and passports.
--environment	Yes	Target environment such as staging or production.
--namespace	Kubernetes scope	Namespace or runtime scope used by Kubernetes and GitOps evidence.
--source-sha	Yes	Commit SHA for release identity and audit traceability.
--artifact	Recommended	Image digest or artifact identifier. Prefer immutable digests over tags.
--release-id	Recommended	CI run, pipeline, deployment, or change request identifier.
--fail-on	Recommended	Which verdict causes non-zero exit, commonly block first, then hold when ready.

CI examples

GitHub Actions

.github/workflows/release.yaml

- name: Release Passport gate
  env:
    RELEASEPASSPORT_TOKEN: ${{ secrets.RELEASEPASSPORT_TOKEN }}
  run: |
    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

GitLab CI

.gitlab-ci.yml

releasepassport_gate:
  stage: pre_deploy
  image: alpine:3.20
  before_script:
    - test -x ./releasepassport || (echo "Install the Release Passport CLI through the portal token-first installer before CI gate execution." >&2; exit 1)
  script:
    - releasepassport gate
      --api-url "$RELEASEPASSPORT_API_URL"
      --token "$RELEASEPASSPORT_TOKEN"
      --mode shadow
      --service checkout-api
      --environment production
      --namespace apps-checkout
      --source-sha "$CI_COMMIT_SHA"
      --artifact "$IMAGE_DIGEST"
      --release-id "$CI_PIPELINE_ID"
      --fail-on block

Jenkins

Jenkinsfile

stage('Release Passport gate') {
  environment {
    RELEASEPASSPORT_TOKEN = credentials('releasepassport-token')
    RELEASEPASSPORT_API_URL = 'https://release-passport.example.com/releasepassport/v1'
  }
  steps {
    sh '''
      releasepassport gate \
        --api-url "$RELEASEPASSPORT_API_URL" \
        --token "$RELEASEPASSPORT_TOKEN" \
        --mode shadow \
        --service checkout-api \
        --environment production \
        --namespace apps-checkout \
        --source-sha "$GIT_COMMIT" \
        --artifact "$IMAGE_DIGEST" \
        --release-id "$BUILD_TAG" \
        --fail-on block
    '''
  }
}

Decision behavior

ALLOW

Evidence is complete enough for the selected policies. In shadow/advisory/enforce it can return exit 0 unless --fail-on is stricter.

ALLOW_WITH_CANARY

Evidence is mostly healthy, but policy requires a constrained canary or progressive rollout before full promotion.

HOLD

Evidence is missing, stale, incomplete, or waiting for a connector. In enforce mode, teams often make HOLD non-zero after shadow confidence.

REQUIRE_APPROVAL

The policy allows a human approval path. Use only when the approval workflow is configured and auditable.

BLOCK

Evidence indicates promotion should stop, such as failing runtime health, missing rollback, policy violation, or unsafe artifact identity.

ROLLBACK_RECOMMENDED

A post-deploy or runtime signal indicates the current release should be investigated for rollback.