Build and promote extensions

Build committed extension source and activate its configuration.

A build uses committed source from a pushed ref. A build never uses local, uncommitted changes.

This guide assumes that you already have extension source under .garage/. To create extension source, run garage ext new <name> or work through Build and run your first extension.

Commit and push the source

git add .garage package.json tsconfig.json
git commit -m "Add extension"
git push

Build the pushed commit

garage ext build

The command builds extension, tool, webhook, and daemon sources and writes descriptor files beside them.

Commit and push the descriptors

git add .garage
git commit -m "Build extensions"
git push

Promote the configuration

garage ext promote

Promotion advances refs/heads/garage to the tip of the source ref. refs/heads/garage holds the promoted configuration. It grants capabilities and activates record schemas, webhooks, and daemons. Built tools can also run from other refs, with capabilities limited by this configuration.

To build and promote from a ref other than the default branch, pass --ref <ref> to both garage ext build and garage ext promote. The option names the source ref in both commands. The destination is always refs/heads/garage.

See the extension reference for source formats and the extension model for how source, builds, and promotion relate.