Preflight

Overview

Preflight is a sample case study for a command-line tool that runs a deploy checklist automatically. Before anything ships, one command confirms that required environment variables are set, database migrations are applied, there is enough disk space, and health endpoints answer.

The problem

Deploy checklists live in wikis and in people's heads. Under time pressure, steps get skipped, and the skipped step is always the one that mattered. Most failed deploys are not exotic. A variable was missing, a migration did not run, or the disk was full.

Goals

• Turn the checklist into code that lives next to the application.
• Run the same checks locally and in CI.
• Finish quickly enough that nobody is tempted to skip it.
• Produce output that a person can scan and a machine can parse.

Technical approach

Checks are declared in a small configuration file in the repository. Each check has a name, a type (environment, migrations, disk, HTTP health, command) and its parameters. The CLI loads the file, runs independent checks in parallel with individual timeouts, and prints a compact report.

The exit code is zero only when every required check passes, so CI can block a deploy without any extra scripting. A JSON output mode makes the same report usable by other tools.

Architecture

Figure 1 shows the flow: a developer or a CI job runs the CLI, the CLI fans out to the checks in parallel, and the results come back together as a single pass or fail report.

Technology stack

• TypeScript on Node.js for the CLI.
• GitHub Actions to run it on every deploy.
• Shell for checks that are easiest to express as a command.

Challenges and solutions

Checks that hang

Every check has a timeout, and a timed-out check fails with a clear message instead of stalling the whole run.

Secrets in output

The environment check reports whether a variable is present and well formed, never its value.

Warnings versus failures

Some checks should warn without blocking, such as disk usage creeping up. Each check declares its severity, and only required checks affect the exit code.

Results

Sample entry. Record real outcomes here, such as how many deploys the tool blocked and why, and how long a full run takes in CI.

Lessons learned

• A checklist in code gets maintained, because it fails loudly when it drifts.
• Fast checks get run. Slow checks get skipped.
• Good error messages say what to do next, not just what went wrong.