Extension model
How source, builds, descriptors, promotion, and capabilities determine what runs.
garage versions an extension with the repository that it extends. garage also keeps the source, the build output, and the active configuration separate. You can therefore review the exact code and capabilities of each run in the repository history.
Extension source
Extension source lives under .garage/:
- extensions respond to pushes, events, or explicit dispatch
- tools expose typed callable operations
- webhooks deliver signed HTTP requests
- daemons run on schedules or repository events
The repository commit identifies the complete source state. A build therefore uses a pushed commit. A build never uses an uncommitted file from the working tree of an author.
Builds and descriptors
A build compiles the source and writes descriptor files beside it. A descriptor records the extension’s public shape, including its schemas, triggers, and requested capabilities.
A committed descriptor keeps the executable configuration and its source in the same history. A later change to the source requires a new build. You can promote that configuration only after the new build.
Promotion
Promotion grants capabilities and activates record schemas, webhooks, and daemons. Built tools and dispatchable extensions can run from an unpromoted branch, but promotion limits the host APIs they can use.
Push-triggered extensions run the pushed branch’s built code and match that branch’s triggers. They run automatically only when an extension with the same name exists in the promoted configuration.
A dedicated ref, refs/heads/garage, holds the promoted configuration.
Promotion advances this ref to the tip of a source ref. Git refuses every push
to refs/heads/garage. garage ext promote is therefore the only command that
moves the ref.
The default branch is the usual source. --ref selects a different source ref
for both garage ext build and garage ext promote. The option always names
the source ref, never the destination.
Capabilities
An extension requests host APIs in its source. Examples include repository reads, repository writes, records, events, and outbound network access.
At run time, an extension receives the intersection of the capabilities it requests and those granted to the same extension name in the promoted configuration. With no promoted entry of that name, it receives no capabilities. Adding a capability on a branch does not grant it; removing a capability on a branch takes effect for runs from that branch.
This rule is important for MCP tools. A client can discover a built tool, but the promoted configuration still limits every repository access of that tool.
See the extension reference for source fields and Build and promote extensions for the procedure.