A Deploy Tool Should Tell You What It Cannot Do

From the team behind aidrop.it — one workspace to build, host, and keep changing your code.

Point a modern deploy tool at a repository and it will usually try: detect a framework, guess a build command, pick a port, start. When that works it feels like magic. When it does not, you get a red log at the end of a four-minute build and no statement of what was missing.

The useful behaviour is the opposite: say what is missing before anything runs. A check that reads a repository and reports "this needs a start command and a port, and I found neither" has told you more in two seconds than a failed build tells you in four minutes.

Call it a preflight. The name matters less than the property: it reports rather than guesses, and it reports before spending your time.

Three verdicts, not two

Pass/fail is the wrong shape, because most real repositories are neither:

• Supported — everything needed was found. Build it.
• Assisted — it can run, but a human has to supply something first: a value, a port, a command. Here is the list.
• Unsupported — this shape is not something the platform runs, and here is which part.

The middle one does the work. Binary tools collapse it into failure, and "failed" is the least actionable word available — it cannot distinguish "your code is wrong" from "I need one thing from you".

What it should actually look for

A useful preflight reads for absence, which is harder than reading for presence and is where generated code fails most often — the same reason reviewing an agent's output means reading for what is not there.

Concretely: how it starts and on what port, every variable the code reads that nobody supplies, everything it expects to write to — uploads and local database files do not survive a container — whether credentials are committed, and whether anything answers to say it is ready. The full list is at the end of this article, in a form you can keep.

The output is a list, not a score

A preflight returning a percentage or a grade has hidden the thing you needed. What you want back is named, checkable items, each satisfied or not, with the unsatisfied ones stated as work.

That list is worth more than the deploy it precedes: it is the shortest honest description of what it takes to run this code — exactly what nobody writes down, and exactly what the next person to open the repository will need. Run it by hand once per project even where no tool does it for you; it is the same list an agent inheriting the codebase needs.

Why this is not the default

Because guessing demos better. A tool that detects and starts looks fast in a screenshot; one that returns five findings looks like homework. The difference shows up on the second day, when the guess was wrong and nothing said which guess it was. There is an incentive problem too: reporting "unsupported" is a platform admitting a limit in public, and it is easier to let a failed build carry the bad news, where it reads as the customer's problem. A tool that will not state its limits has moved the cost of discovering them onto you.

The checklist, to keep in the repository

Whatever you deploy with, these are the answers a first deploy needs. Save it as DEPLOY-PREFLIGHT.md next to your code and fill it in once — it is the same list an agent inheriting the repository needs, so writing it serves both.

# Deploy preflight

- [ ] Start command:
- [ ] Listens on port:            (from $PORT, not hard-coded?)
- [ ] Health endpoint:            (returns 200 when ready)
- [ ] Build command:              (or: Dockerfile at the root)

## Environment
- [ ] Every variable the code reads, and where each value comes from:
- [ ] Any read at import time rather than at request time:

## State
- [ ] Written to disk anywhere?   (uploads, cache, a local database file)
- [ ] Where each of those belongs instead:

## Blockers
- [ ] Credentials committed to the repository?   → rotate before deploying
- [ ] Anything reached on a port other than 80 or 443?

Every unticked line is a finding, and a finding is work rather than a failure — which is the whole distinction this article is about. If a tool hands you this list before it builds, it has earned the four minutes it is about to spend.

FAQ

What is a deployment preflight? A check that reads a repository and reports what is needed to run it, before any build starts. It returns named findings rather than a pass or a fail, and distinguishes "cannot run" from "needs one thing from you". On aidrop.it there is no separate preflight: a build is the check, and when one fails it reports what stopped it.

Why does my first deploy fail with no useful error? Usually a missing environment variable or a port the code hard-codes. Both are visible by reading the repository, which is why a check that runs first saves the build time entirely.

Is "assisted" not just a nicer word for failed? No — it names the difference between your code being wrong and the platform needing something from you. Collapsing them into "failed" is what makes a red log unactionable.

Can an AI agent run this check for me? It can gather it, and it is good at reading a repository for absences. What it should not do is supply the missing values — anything passed through a tool call is written into context and logs, so credentials stay a human step.

Cover: https://commons.wikimedia.org/wiki/File:Preflight_checklist_(14443492762).jpg by US Air Force, Public domain, via Wikimedia Commons. Cropped to 16:9 within the original frame. Alt text: A pilot reading a preflight checklist in an aircraft cockpit before departure.