Building blocks
Concept
See How it works for the step-by-step flow from idea to production; this page names the pieces you’ll see mentioned throughout. Every app your citizen developers build is composed from the same seven primitives — mostly declared once in a manifest, not called into existence one MCP request at a time.
The seven pieces
Section titled “The seven pieces”| Primitive | What it is |
|---|---|
| App | The governed unit — one repo, one shared environment, one deployed workload. |
| Workloads | The compute the app runs as. |
| Resources | App-owned infrastructure — a database, file storage. |
| Integrations & grants | Governed access to external and internal systems. |
| MCP tools | The interface the agent drives Greenlight through. |
| Environment variables | Names the agent declares; values it never sees. |
| Knowledge | The context the agent reads every session. |
The governed unit: one repository, one shared environment, one deployed workload today. registerApp creates the scaffold — the app record and a seeded repo — but the app stays in a registered state with no running infrastructure until the first merged pull request declares a workload. See App deployment & isolation.
Workloads
Section titled “Workloads”The app’s runnable shape, declared in greenlight.yml’s workloads: block — kind, dockerfile, port, and the routes it serves. Every app gets one web workload today; additional workload kinds are on the roadmap. See App deployment & isolation and greenlight.yml.
Resources
Section titled “Resources”Managed infrastructure the app asks for — a Postgres database, an object storage container — declared in resources: by kind and name. Greenlight provisions each one on merge with scoped credentials and injects its managed environment variables automatically (DATABASE_URL for a Postgres resource, for example). See App deployment & isolation and greenlight.yml.
Integrations & grants
Section titled “Integrations & grants”Governed access to the external and internal systems an app needs — Slack, Snowflake, an internal REST API, a connected database. An app’s own access is declared as grants: in the manifest, auto-approved where policy allows and queued for IT review otherwise; a person’s own access is requested imperatively with requestCredentialAccess. Either way, the app never holds the upstream credential — the data broker supplies it per call. See Data brokering.
MCP tools
Section titled “MCP tools”The interface the agent actually drives Greenlight through — registering the app, opening and merging pull requests, reading pipeline results, reading logs, requesting a preview, reading and proposing Knowledge. Where the primitives above are mostly declared in the manifest, MCP is how the agent operates and observes the result. See The agent protocol and the MCP tools reference.
Environment variables
Section titled “Environment variables”Two kinds live on every app: user-declared names in the manifest’s env: block, whose values are written separately with envSet and never committed to the repo, and managed names Greenlight derives automatically from the app’s resources and grants (DATABASE_URL, GREENLIGHT_DATA_KEY, and the like). A secret value never crosses MCP to the agent. See App environment variables.
Knowledge
Section titled “Knowledge”Org-, integration-, and app-scoped prose the agent reads at the start of every session and can propose additions to as it learns — a connection’s quirks, an app’s architecture, a team’s conventions. It’s customer-specific and evolving, distinct from the universal Skills that teach the agent the Greenlight protocol itself. See Knowledge.
Mostly declared, not called
Section titled “Mostly declared, not called”Most of what’s above is declarative: the agent edits workloads, resources, grants, and env names in greenlight.yml and opens a pull request; on merge, Greenlight provisions and reconciles the difference. MCP is the exception — it’s how the agent registers the app in the first place, ships that change, and reads back everything else. The full mechanics of that split live in The agent protocol.