Docs

Deployments.

A Deployment is one full build-and-deploy run of a Service. Every git push, CLI trigger, or API call produces exactly one Deployment record you can inspect, stream logs from, or roll back to.

Deployment lifecycle

Each Deployment moves through a fixed sequence of states. Understanding the states helps you know where to look when something stalls.

  • queued - The trigger was received and the Deployment is waiting for a builder slot. High-concurrency projects may sit here briefly.
  • building - A Build is running: Nixpacks detects your language, installs deps, and produces a container image. This is usually the longest phase.
  • deploying - The new image is being placed on the target region and health checks are running. Traffic stays on the old instance until checks pass.
  • succeeded - Health checks passed. Traffic has cut over to the new instance. The previous instance is stopped.
  • failed - The build crashed, the image could not start, or health checks timed out. The previous instance keeps running. Build logs are preserved.
  • cancelled - A newer push superseded this one while it was still queued or building, or you cancelled it manually.

The Build step

Inside every Deployment is a Build - the Nixpacks phase that turns your source code into a runnable container image. Nixpacks inspects the repo root, auto-detects the runtime (Node, Python, Go, Rust, etc.), and produces a deterministic image. You can override the detected start command or install phase via fieldwick.json.

// fieldwick.json (optional overrides)
{
  "build": {
    "buildCommand": "pnpm run build:prod",
    "startCommand": "node dist/server.js"
  }
}

Build logs are stored for every Deployment whether it succeeded or failed. Use the CLI to tail them in real time or retrieve them later.

# Stream build logs while a deployment is in progress
fieldwick logs <service> --deployment <id> --build

# View build logs for a past deployment
fieldwick logs <service> --deployment <id> --build --no-follow

Listing deployments

Every Deployment gets a short immutable ID (for example dep_01j9z). Use the list command to see recent history for a Service.

fieldwick deployments list <service>

# Example output
ID          STATUS     TRIGGERED   REGION       COMMIT
dep_01j9z   succeeded  2 min ago   us-east-1    feat: add dark mode (#48)
dep_01j9y   failed     18 min ago  us-east-1    fix: typo in env key
dep_01j9x   succeeded  2 hr ago    eu-central-1 chore: bump deps

Pass --json for machine-readable output, or --region us-east-1 to filter by region.

Rollback and redeploy

Rolling back promotes a previous successful Deployment's image to live traffic without re-running the build. It creates a new Deployment record with source: rollback so your audit trail stays clean.

# Roll back to a specific past deployment
fieldwick deployments rollback dep_01j9x

# Roll back to the most recent succeeded deployment (skips current)
fieldwick deployments rollback <service> --latest-good

To redeploy the exact current commit (for example, to pick up a changed env var), use fieldwick deploy with no extra flags from inside the repo. The build re-runs from the same ref already on the Service.

CI and automation

In a CI pipeline or agent workflow you usually want the deploy command to block until the Deployment finishes and return a meaningful exit code so the pipeline can gate on success.

# --wait blocks until succeeded or failed (default timeout: 10 min)
fieldwick deploy --wait

# Exit codes:
#   0  succeeded
#   1  failed
# 124  timed out (deployment may still be running)

# Override the timeout (seconds)
fieldwick deploy --wait --timeout 600

For agent workflows that need structured progress events - such as streaming status into a tool call or a webhook handler - use the watch/wait ndjson pattern. Each line is a self-contained JSON event so your agent can parse state changes without polling.

# Watch a deployment and emit ndjson events to stdout
fieldwick deployments wait dep_01j9z --json

# Each line is a JSON object, for example:
{"event":"state","deployment":"dep_01j9z","state":"building","ts":"2026-06-05T14:01:00Z"}
{"event":"log","deployment":"dep_01j9z","stream":"build","line":"Installing deps...","ts":"2026-06-05T14:01:03Z"}
{"event":"state","deployment":"dep_01j9z","state":"deploying","ts":"2026-06-05T14:02:41Z"}
{"event":"state","deployment":"dep_01j9z","state":"succeeded","ts":"2026-06-05T14:02:58Z"}

GitHub Actions example - deploy and fail the job on a bad deploy:

- name: Deploy to Fieldwick
  run: fieldwick deploy --wait
  env:
    FIELDWICK_TOKEN: ${{ secrets.FIELDWICK_TOKEN }}

API and webhook triggers

Beyond git push and the CLI, you can trigger a Deployment from any HTTP client using the REST API. Useful for release automation, MCP tool calls, or deploying from a monorepo script.

# Trigger a deploy via the REST API
curl -X POST https://api.fieldwick.com/v1/services/<service-id>/deployments \
  -H "Authorization: Bearer $FIELDWICK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref": "main"}'

# Response (202 Accepted)
{
  "id": "dep_01ja2",
  "state": "queued",
  "service": "<service-id>",
  "region": "us-east-1",
  "ref": "main"
}

After triggering via the API you can hand the returned id straight to fieldwick deployments wait <id> --json to stream progress without polling.