Manage policies
Admin guide
The deploy checks are the rules Greenlight evaluates on every pull request, at the policy check, to decide whether a commit may deploy. As an Admin or Org Owner you control which checks are active, whether each one blocks or merely warns, and the values the configurable checks compare against. This page walks the day-to-day workflow. The concepts behind it — what the policy set is and how OPA evaluates it — are in Governance & policy.
Every organization starts governed by the shipped checks, so there is nothing to set up before your first app. Everything below is optional and incremental.
Open the Policies surface
Section titled “Open the Policies surface”Policy management lives in Settings → Policies. Admins and Org Owners see it; Builders do not — policies are org-wide governance.
The page lists every shipped check: its name and description, its state (Active, Off, or Needs config), and whether it is set to block or warn. A configurable check with nothing configured yet is silent — it never blocks everything for want of a list.
Set enforcement: block or warn
Section titled “Set enforcement: block or warn”Each check is either block or warn:
- Block — a violation fails the policy check and the commit does not deploy.
- Warn — a violation surfaces in the check detail and the audit log but does not stop the deploy. Use warn when you want visibility without gating.
Change a check’s enforcement from its row. The change is audited and takes effect on the next run.
Where each check starts
Section titled “Where each check starts”Where a check starts comes down to one question: can whoever the block lands on actually do something about it?
Checks that report findings in your code — secrets, critical dependency CVEs, base images, committed .env files — start in warn. How many findings a repository produces depends on the history it arrived with, and a first deploy that fails on that history helps nobody. Review what they report, clean up what matters, then promote them to block.
Checks that validate an app’s manifest start in block: that greenlight.yml parses, that it only requests integrations and credentials you registered, that it stays inside your resource kinds and compute caps. These aren’t findings to triage — a manifest that doesn’t parse, or that reaches past what you granted, would deploy a broken or over-permissioned app, and the fix is in the change itself.
Resource limits required starts in warn for a different reason: it reads the deployment Greenlight generates, not your code. It can only fail if something is wrong on our side, which nobody on your team can fix — so it reports rather than blocking your merge.
You can move any check in either direction; this is only where it starts.
Require your own scanners
Section titled “Require your own scanners”If your organization already runs CodeQL, Snyk, or another scanner on GitHub, you don’t have to choose between it and Greenlight. Under Your own scanners, name the check it posts and Greenlight will treat it as first class: required before merge, and its findings relayed to the coding agent — which never has GitHub access and otherwise has no way to learn why its pull request is held.
You give two things:
- Check name — exactly as the scanner posts it (for example
CodeQL). - GitHub App id — the numeric id of the app that posts it, from that app’s settings page in GitHub.
The app id is required on this path, and it is the point. Without it, a check is matched on name alone — and anything able to write a status to your repository could satisfy it by posting that name. Naming the app means only the genuine scanner can turn the check green.
Paste steps Greenlight runs
Section titled “Paste steps Greenlight runs”If the scanner is not already wired into every app repo — and in Greenlight repos the CI file is Greenlight-owned — paste a YAML step list instead. Greenlight runs those steps in an isolated job on every app pipeline (contents: read only; they cannot see Greenlight’s secrets or evidence). The check that job posts is required the same way as a named check. You do not paste a GitHub App id.
Paste a list of steps, not a workflow document (on: / jobs:). Invalid YAML, or a step that reaches for secrets, GREENLIGHT_PIPELINE_TOKEN, or greenlight-evidence/, is refused with the offending line — it is never written into the fleet.
Greenlight schedules the steps; it does not vouch for them. They run in your repositories on GitHub-hosted runners and cost your CI minutes.
A newly added check starts in warn: it reports on every run without holding a merge, so you can see what it finds on your repositories first. Promote it to block when you’re ready, and Greenlight re-applies the requirement across your existing repositories, not just ones created afterward. Softening or removing it walks them back the same way. Pasted steps also rewrite every app’s generated workflow when you add, edit, disable, or remove them.
That re-application happens while you wait, and it can be partial — a repository whose branch protection or workflow file could not be written stays on the previous setting. When that happens the page names those repositories rather than reporting a plain success, because a repository still requiring a check you just removed will hold every pull request open on it. Saving the check again retries them.
A required check that never posts a result is reported on the run with the reason, rather than leaving a pull request waiting with nothing to explain it.
What the agent sees. The scanner’s own summary and a link to its findings, relayed as-is — Greenlight doesn’t reinterpret another tool’s verdict. Line-level findings from GitHub code scanning need a GitHub Advanced Security license and aren’t read today, so agents can act on the summary but can’t auto-fix from it.
Enable or disable a check
Section titled “Enable or disable a check”Disabling a check takes it out of evaluation entirely — it neither blocks nor warns. Re-enabling restores it with its configuration intact. Prefer warn over disable when you still want visibility; disable only when a check genuinely doesn’t apply to your org.
Edit a check’s configuration
Section titled “Edit a check’s configuration”The configurable checks carry the specifics they enforce. The form adapts to the check you’re editing:
| Check | What you configure |
|---|---|
| Approved base images | The list of allowed Docker base images (e.g. node:20-alpine, python:3.12-slim), with a one-click recommended starter list. Until a list exists the check is silent. |
| Workload compute within cap | The CPU and memory ceilings a workload may request. |
| Declared resource kinds | Which resource kinds (postgres, blob) an app manifest may declare. |
Greenlight validates the configuration before storing it — an invalid value is rejected with an explanation and never reaches the evaluator. A valid change is audited and effective for the next run.
The one check you cannot weaken
Section titled “The one check you cannot weaken”Secrets in code are always reported. Every detected secret appears on the run whatever your settings say. Whether it blocks the merge is yours to choose, like any other check: leave it on block, or set it to warn while you work through a backlog of findings. Setting it to warn does not hide anything — the findings still show on every run, and the change is audited like any other.
Read the latest results
Section titled “Read the latest results”The same page shows each app’s most recent default-branch run: which checks ran and what each decided, with the failing detail inline. It answers “what is the gate actually doing to my fleet” without opening each app’s run history.
What’s audited
Section titled “What’s audited”Every enforcement change, enable/disable, and configuration edit writes an audit event capturing the actor, the check, and the change. The audit log is the source of truth for “when did this policy change, and who changed it” — the question a compliance review eventually asks.