Source control & the policy check

Concept

Greenlight enforces a single delivery path: pull request, policy check, merge, deploy. There are no out-of-band writes and no shortcuts. The same path applies to the coding agent, the citizen developer, and IT.

What the check runs

Greenlight’s policy check is a single status that posts on every pull request and aggregates four kinds of analysis.

Check	What it catches
Secret scanning	API keys, tokens, and private keys committed in the diff.
Static analysis	Known-bad patterns, OWASP rules, and any custom organization rules you’ve enabled.
Supply chain	Container CVEs, dependency vulnerabilities, and license-policy violations.
Org policy bundle	Organization-specific rules evaluated by OPA — approved base images, resource limits, dependency allow-lists, and anything else in your policy bundle.

The policy bundle is org-scoped, and changes to it live as structured rows. Adding a rule means inserting a row in the dashboard, not redeploying the platform.

What the PR shows

A pull request that passes the check shows a single green status from Greenlight and is mergeable through the normal source-control flow. A pull request that fails shows the same status with a structured reason that the agent reads and acts on:

✗ greenlight/policy-check          Failed (2/4 checks)
  • secret-scanning: API key found in src/integrations/snowflake.ts
  • org-policy/approved-base-images: base image not on the allow-list

Status: merge blocked

What a policy looks like

Policies are structured data, not free-form scripts. A representative base-image policy:

id: approved-base-images
kind: deny_if
description: Containers must use an approved base image.
match:
  resource: dockerfile
  field: from
  not_in:
    - ghcr.io/shiftengineering/node:20-alpine
    - ghcr.io/shiftengineering/python:3.12-slim
on_violation:
  status: failed
  message: "Base image not on the approved list."

The agent can read the active policy set at any time via the greenlight.getPolicies MCP tool — so it can fix violations on the first try instead of guessing.

What happens on failure

1. The status goes red. The PR comment includes the structured failure reason.
2. The agent reads the failure. Either from the PR comment or by calling getPolicies to compare its diff against the active rules.
3. The agent fixes and pushes. Same branch, same pull request. The check re-runs automatically.
4. The status goes green. The PR becomes mergeable. Merging triggers deployment.

Caution

An IT admin can override the policy check in an emergency. Every override writes an audit event with the reviewer’s identity, the failed checks they overrode, and the reason they entered. The frequency of overrides surfaces in the audit dashboard.

Next

Governance & policy RBAC, the kill switch, and the override audit trail.

Audit & evidence What every action looks like in the log.

MCP tools reference getPolicies, registerApp, knowledge.*, and the rest.

Knowledge How the agent reads context — and why it's separate from policy.