Extension Block

The extension block adds functionality to Terrabuild. Extensions defined in WORKSPACE are global to the workspace and apply to all projects unless overridden in a PROJECT file. Extensions can be used in PROJECT files to initialize projects or execute actions within targets.

Extensions provide commands (actions) that can be executed within targets. An extension can run in a container to provide isolation and repeatability, ensuring consistent builds across different environments. See Container for more technical information.

Example Usage

extension @dotnet {
  container = "mcr.microsoft.com/dotnet/sdk:8.0"
  platform = "linux/arm64"
  variables = [ "SECRET_VAR" ]
  batch = true
  defaults = {
    configuration: $configuration
  }
}

Argument Reference

The following arguments are supported:

• identifier - (Mandatory) Identifier of the extension. Must start with @ (e.g., @dotnet, @npm, @docker).
• container - (Optional) Docker image in which actions will be executed. This provides isolation and ensures consistent build environments. If not specified, actions run on the host.
• platform - (Optional) Target platform for the container image (e.g., linux/arm64, linux/amd64). Useful for cross-platform builds.
• variables - (Optional) A list of environment variable names to pass from the host to the container. This allows secrets and configuration to be passed securely.
• batch - (Optional) Enable batch support for the extension, allowing multiple actions to be grouped together for efficiency. Default is false.
• defaults - (Optional) Default values used as action arguments. This is a mapping of expressions that will be applied to all actions using this extension unless overridden in a PROJECT file.
• script - (Optional) F# script used to implement a custom extension. The argument is a relative path to the .fsx file. See Script Extensibility for more information.