Plugins

Almost everything heph can do comes from plugins. Plugins come in three kinds: a driver is a named executor a target references via its driver field; a provider discovers or generates targets; a hook observes the engine's build-event stream without producing or running anything. For example, when you write driver = "bash" in a BUILD file, you are reaching for a driver registered by the Exec plugin; when heph scans the workspace for BUILD files, that is a provider at work.

Naming

A plugin's drivers are named <plugin>.<driver> in a BUILD file: driver = "oci.pull", driver = "go.lint", driver = "devenv.runner", driver = "auth.credential". A plugin's functions are heph.<plugin>.<function>, such as heph.fs.glob and heph.auth.env. A driver that carries the plugin's own name, like bash or group, is written bare.

List every loaded plugin with the full name of each driver, function and runner it provides:

terminal

heph tool plugins
heph tool plugins --json

Drivers

Each driver plugin registers one or more named executors a target can run through.

Plugin	Driver	Purpose
Exec	exec, bash, sh	Runs shell commands in sandboxed builds, with interactive debugging.
Filesystem	fs	References workspace files and globs as build inputs.
Group	group	Bundles targets transparently with no extra work.
Hostbin	hostbin	Wraps host PATH binaries as targets for the build system.
HTTP Fetch	http_fetch	Downloads a URL, templated over the target's address args, into a cacheable file output.
Nix	nix	Builds reproducible tool environments via Nix flakes.
Template	template	Renders a template file with declared variables into a cacheable output.
Textfile	textfile	Generates text files with optional executable permissions.

Languages

Language plugins add first-class support for a toolchain, registering the drivers that build its libraries, binaries, and tests.

Plugin	Driver	Purpose
Go	go.golist, go_embed, go.testmain	Go language support: libraries, binaries, tests.

Containers

The OCI plugin builds and moves container images, with or without a Dockerfile and with or without a daemon.

Plugin	Driver	Purpose
OCI	oci.docker_build, oci.image, oci.layer, oci.index, oci.pull, oci.push, oci.load, oci.runner	Build an image (with a Dockerfile or from target outputs), group multi-platform images, move images between a registry, the cache, and a local docker daemon, and run targets inside a running container.

Runners

A runner target describes an environment other targets run inside — a devenv shell, a container — instead of on the bare host. Any Exec or Go target can point at one.

Plugin	Driver	Describes
Devenv	devenv.runner	A devenv shell.
OCI	oci.runner	A running container.

Providers

Each provider plugin discovers or generates targets rather than executing them, so it registers no driver.

Plugin	Purpose
Buildfile	Scans the workspace for BUILD files and parses target definitions.
Query	Selects targets dynamically by label, package, prefix, or output.

Hooks

Hook plugins observe the engine's BuildEvent stream — targets matched, started, finished, cache hits, failures — without producing or running targets. They are purely build-event consumers and run in the same process as heph on a background thread.

Plugin	Purpose
GitHub Actions	Live PR comment and step summary for GitHub Actions builds.