Plugins

Up is built from small parts. A plugin adds one part. A plugin can add a code host, a capability, a builder, or a runtime. The platform does the deploy. The plugin does the work that is special to one external system.

Parts of up

A forge is a code host. It starts a deploy. It reads events from GitHub or another host. GitHub is the first forge. This page uses the word forge for a code host.
A capability gives the platform a service it needs. Examples are DNS and tunnels. This part is not built yet.
A builder makes an image. Railpack and Dockerfile are the builders today.
A runtime runs a container. The container runtime is the runtime today.

A plugin can add one part or many parts. Most plugins add one part.

How a deploy starts

GitHub sends an event to the control node. The event is a push or a pull request.
The plugin checks the event signature. It reads the event and makes a simple event. The simple event has no GitHub words in it.
The platform chooses the environment. The default branch becomes production. Another branch keeps its name. A pull request becomes pr-<number>.
The plugin gets up.yaml from the repository. It also gets a short-lived token.
The platform plans and applies the change. This is the same code that runs for any other apply.
The plugin reports the result in the words of its provider. On GitHub, the result is a check run, a deployment, and a pull request comment.

Why the platform owns the apply

The apply code is one path. Every plugin uses that path. A new code host cannot change how up builds, deploys, or reports. So two code hosts cannot act in different ways.

Plugin settings

Plugin settings are in the control node config file. They use the plugin id:

[plugins.github]
app_id = 123456
private_key_path = "/home/deploy/.config/up/plugins/github/app.pem"
webhook_secret = "the-webhook-secret"
public_url = "https://up.example.com"

public_url is optional. The setup flow uses the top-level public_url from the control node config when the plugin table does not set one, then node_url when it is not a loopback address. Because the GitHub webhook must be reachable from GitHub, a loopback node_url is refused; set a public URL instead.

The settings stay on the control node. They hold secrets. The node config API cannot change them.

Commands

A plugin declares its commands. The CLI turns the declaration into commands. So up plugin github init works without a second list of commands.

Run up plugin to see the plugins on the control node.