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.
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 selects the repository configuration that garage runs. Unpromoted source can stay on a branch for review. It does not change the active tools, triggers, webhooks, or daemons.
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.
Promotion grants the capabilities that the reviewed configuration requests. At run time, an extension can use only the capabilities in the promoted configuration. A capability in unpromoted source stays ungranted.
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.