Build output API

Last updated: 2026-03-17

Forgeon analyzes build outputs to determine runtime configuration.

What Forgeon expects

• A build artifact (static or server)
• A start command (for server)
• A port (for web services)

Build output contract (simplified)

Your build should produce metadata that answers:

• What type of workload is this (static or runtime)?
• What command starts the app?
• Which internal port should receive traffic?
• Which files are the deploy artifact?

If this metadata is incomplete, deployment can succeed but runtime may fail to serve traffic.

Where output is used

• Build system selection (Template / Nixpacks / Buildpacks)
• Runtime config persistence
• Deploy pipelines

Minimal examples

Static app

• Build output folder exists (for example dist/ or build/)
• No server process required
• Edge serves generated assets directly

Runtime app

• Start command exists (for example node server.js)
• App listens on 0.0.0.0:$PORT
• Health/readiness endpoint is configured when possible

Validation checklist before deploy

• Build command runs clean in CI.
• Output folder or image artifact exists.
• Start command is executable in target environment.
• Internal port matches actual app listener.
• Required env vars are available per environment.

Troubleshooting

Wrong build system picked

• Set build system explicitly and redeploy

Build succeeded, runtime unreachable

• Confirm app is listening on 0.0.0.0:$PORT, not localhost.

Image reference missing

• Ensure build stage publishes artifact metadata before runtime stage starts.

See also

• Deployments
• Configuration reference