Catching .neo.yml Mistakes Before They Reach the Server

Failing before the expensive part

Building a Docker image and transferring it takes real time. Finding out an environment has no server: configured after that transfer is a wasted deploy. Neo validates .neo.yml structurally before anything gets built:

environments:
  staging:
    domain: staging.example.com
    # missing server: — caught immediately

✗ environment "staging" has no server: defined in .neo.yml
  → Add to the "staging" environment:

    environments:
      staging:
        server: your-server-name

Root-level fields that get silently ignored

When environments: exist, a root-level server: or domain: doesn't apply to any of them — deploy uses the environment's own values. Rather than let that be a confusing silent no-op, Neo errors and shows exactly where the value should move:

✗ root-level domain:/domains: is ignored when environments: are defined
  → Move domains: into each environment block

--all needs every environment fully specified

Because neo deploy --all builds once and fans out to every environment, it's stricter than a single-target deploy: every environment must name a server, and (as covered in One Dockerfile Per Environment) they must agree on which Dockerfile to build. A single neo deploy --to staging only validates the environment you're targeting.

The practical effect

These checks turn "deploy failed halfway through, on server three of five" into "deploy refused before it started, here's exactly what's wrong" — the difference between debugging a partial rollout and fixing one line in a config file.