Guia público

Gate Deploys with Hosted Rego Guardrails

Add a lightweight CI step that sends deploy context to your tenant and gets an allow, warn, or deny decision back without self-hosting OPA. Público: Platform engineers, release managers, and security engineers. Tempo típico de configuração: 3 minutes.

quickstart

Use isto se

Add a lightweight CI step that sends deploy context to your tenant and gets an allow, warn, or deny decision back without self-hosting OPA.

Audience: Platform engineers, release managers, and security engineers
Typical time: 3 minutes

Antes de começar

Install the managed starter pack in Policies and keep it in advisory mode for the first rollout.
Create or reuse a tenant API key in Settings → API Keys for your CI system.
Identify the service ID, target environment, artifact name, and branch values your deploy pipeline already exposes.

Caminho rápido

Copy a working starter, run it in your environment, then come back here for the deeper rollout details.

Obtém o bundle de código fonte

Descarrega os ficheiros exatos usados neste guia ou executa o instalador de um só comando para os escrever localmente antes do deploy.

GitHub Actions deploy gate

Writes `.github/workflows/deploy-guardrails.yml` with a hosted policy decision step that runs before production deploys.

.github/workflows/deploy-guardrails.yml

bash

BLACKSHIELD_POLICY_IMAGE=public.ecr.aws/blackshield-security/policy-client:1.0.0 \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/github-policy-guardrails.sh)

Descarregar fonte

GitLab deploy gate job

Writes `.gitlab/deploy-guardrails.yml` with a reusable hosted policy decision job and the current platform API URL prefilled for production deployments.

.gitlab/deploy-guardrails.yml

bash

BLACKSHIELD_POLICY_IMAGE=public.ecr.aws/blackshield-security/policy-client:1.0.0 \
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/gitlab-policy-guardrails.sh)

Descarregar fonte

Executar isto

One-shot policy decision from any shell

bash

docker run --rm \
  -e BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
  -e BLACKSHIELD_API_KEY=sp_xxxx \
  -e POLICY_SERVICE_ID=payment-gateway \
  -e POLICY_TARGET_ENVIRONMENT=prod \
  -e POLICY_REPOSITORY=acme/payment-gateway \
  -e POLICY_ARTIFACT=ghcr.io/acme/payment-gateway:${GIT_SHA:-latest} \
  -e POLICY_BRANCH=main \
  -e POLICY_CONTEXT_JSON='{"reviewer":"release-manager","change_ticket":"CAB-2026-0321"}' \
  public.ecr.aws/blackshield-security/policy-client:1.0.0

GitHub Actions deploy gate

yaml

- name: Evaluate hosted deploy guardrails
  run: |
    docker run --rm \
      -e BLACKSHIELD_API_URL="${{ vars.BLACKSHIELD_API_URL }}" \
      -e BLACKSHIELD_API_KEY="${{ secrets.BLACKSHIELD_API_KEY }}" \
      -e POLICY_SERVICE_ID="payment-gateway" \
      -e POLICY_TARGET_ENVIRONMENT="prod" \
      -e POLICY_REPOSITORY="${{ github.repository }}" \
      -e POLICY_ARTIFACT="ghcr.io/acme/payment-gateway:${{ github.sha }}" \
      -e POLICY_COMMIT_SHA="${{ github.sha }}" \
      -e POLICY_BRANCH="${{ github.ref_name }}" \
      -e POLICY_ACTOR="${{ github.actor }}" \
      -e POLICY_CONTEXT_JSON='{"reviewer":"${{ github.actor }}","pipeline":"deploy-production"}' \
      public.ecr.aws/blackshield-security/policy-client:1.0.0

GitLab CI deploy gate

yaml

deploy-guardrails:
  stage: deploy
  image: public.ecr.aws/blackshield-security/policy-client:1.0.0
  script:
    - python -m policy.entrypoint
  variables:
    BLACKSHIELD_API_URL: "https://api.blackshield.chaplau.com"
    # BLACKSHIELD_API_KEY: set in CI/CD -> Variables (masked)
    POLICY_SERVICE_ID: "payment-gateway"
    POLICY_TARGET_ENVIRONMENT: "prod"
    POLICY_REPOSITORY: "$CI_PROJECT_PATH"
    POLICY_ARTIFACT: "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"
    POLICY_COMMIT_SHA: "$CI_COMMIT_SHA"
    POLICY_BRANCH: "$CI_COMMIT_REF_NAME"
    POLICY_ACTOR: "$GITLAB_USER_LOGIN"
    POLICY_CONTEXT_JSON: '{"reviewer":"$GITLAB_USER_LOGIN","pipeline":"deploy-production"}'

Entender e personalizar

Use the guided steps below when you want to tailor the rollout, validate ownership, or expand the deployment safely.

Passo 1

Install the managed starter pack in the tenant

Open the Policies console, keep the starter pack in advisory mode first, and tune thresholds before enforcing production blocks.

Open Policies in the dashboard and review Starter Deploy Guardrails.
Confirm environments, severity thresholds, freshness window, and fail-open or fail-closed behavior.
Run a simulation with a representative production payload before wiring CI.
Publish any tenant-specific custom Rego only after the draft validates cleanly.

Como é o sucesso

Publish any tenant-specific custom Rego only after the draft validates cleanly.

Open Policies · Requer login

Passo 2

Store the existing tenant API key in CI

The hosted decision API reuses the same tenant API key pattern as other machine-to-machine workflows, so no extra auth system is required.

Create or reuse a scoped API key in Settings → API Keys.
Store `BLACKSHIELD_API_URL` and `BLACKSHIELD_API_KEY` in your CI secret store.
Map service, environment, branch, artifact, and actor metadata from your pipeline variables.
Start with advisory rollout mode so warn outcomes surface without blocking releases.

Como é o sucesso

Start with advisory rollout mode so warn outcomes surface without blocking releases.

Open API Keys · Requer login

Passo 3

Add the policy client job to your deploy pipeline

Run the policy client before the real deployment step. It posts the deploy request, prints reasons, and exits non-zero only when the final decision is deny.

Bootstrap the GitHub Actions or GitLab source bundle from this guide, then commit it to your repo.
Set `POLICY_SERVICE_ID`, `POLICY_TARGET_ENVIRONMENT`, and any optional repository or artifact fields.
Pass reviewer, ticket, or promotion metadata through `POLICY_CONTEXT_JSON` when your tenant policies expect it.
Place the job immediately before the production deploy so the decision reflects the current release candidate.

Como é o sucesso

Place the job immediately before the production deploy so the decision reflects the current release candidate.

Deploy the Pipeline Scanner

Como é o sucesso

The policy client returns `allow` or `warn` for a healthy sample deploy and exits with code 0.
A seeded or simulated high-risk release returns `deny` and blocks the deploy stage with clear reasons.
Decision history in Policies records the request summary, matched policies, and final outcome.

Continuar

Keep your rollout moving with the next recommended step.

Rever e priorizar achados

Links úteis

Open Policies Open API Keys Deploy the Pipeline Scanner

Guias relacionados

Gate Deploys with Hosted Rego Guardrails | Documentação BlackShield