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 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:26-alpine, python:3.14-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. |
| Workload compute matches the sizing guidance | The CPU and memory a workload can declare before the run carries a sizing warning (default 0.25 vCPU / 0.5 GiB). |
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 that only ever warns
Section titled “The one check that only ever warns”Workload compute matches the sizing guidance flags an app declaring more CPU or memory than the sizing guidance suggests. A declared compute: block reserves that capacity for as long as the app is deployed, whether or not the app uses it, so an over-sized value quietly holds cluster capacity nobody else can schedule. The check exists to put that in front of a person before it reaches the cluster — and it stops there. It never blocks a merge and cannot be promoted to block: an app team’s sizing isn’t wrong on its face, and holding their merge over it asks the wrong people to solve a fleet-wide problem. Internal Health shows you the other half of the picture: which running apps are holding the most capacity they don’t use.
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.
Set audit log retention
Section titled “Set audit log retention”Audit log retention sets how long Greenlight keeps the audit log: 90 or 180 days, 1, 2 or 7 years, or Keep indefinitely. New installs start at 90 days. Pick a window, then Save. If the new window is shorter, the page tells you before saving that older events are permanently deleted at the next nightly cleanup. Details: Observability and audit — Retention and exports.
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, configuration edit, and retention change writes an audit event capturing the actor, what changed, and the old and new values where there are any. 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.