Writing DevOps Runbooks with ChatGPT and Codex

I use ChatGPT to organize sanitized notes and Codex to compare a runbook with the repository commands it describes. The first draft is documentation, not an approved procedure. I test every command in a safe environment and record the expected output before another developer relies on it.

A useful runbook helps an operator decide whether to continue, stop, or escalate. A list of commands without targets and failure conditions can make an incident worse.

Name the goal and owner

The title describes the outcome, such as restoring a failed deployment or rotating an API credential. The first section names the service owner, approver, communication channel, and situations where the runbook applies.

I include explicit non-goals. An application restart procedure should not imply permission to change database schema or DNS.

List prerequisites

I record required access, tool versions, working directory, environment, backup state, and safe identifiers. Secret values remain in the owning secret manager. The operator verifies account and region with read-only commands.

Missing prerequisites stop the procedure. The runbook does not tell someone to work around access controls during an incident.

Use copy-safe commands

Commands use explicit targets and descriptive placeholders. I avoid unresolved destructive variables and broad recursive paths. Each command states whether it reads or changes state.

ChatGPT may improve wording, while Codex checks package scripts and file paths. I compare every suggestion with current code and official tool documentation.

Show expected output and branches

After each important command I include a short expected result and the next action for success or failure. Exact volatile output is less useful than a stable signal such as status, count range, or commit hash.

I define escalation points. Repeating a failed write command without understanding the error is not recovery.

Document rollback

The rollback section identifies the prior artifact, data restore point, configuration snapshot, and approval needed. Some changes cannot be reversed by redeploying code, so the runbook separates application, infrastructure, and data steps.

I test rollback in a non-production environment and record limitations rather than promising full recovery.

Exercise and maintain the runbook

Another developer follows the draft without oral help. I note unclear steps, missing access, unsafe assumptions, and elapsed time. The owner updates the runbook after platform or repository changes.

• Goal and scope are explicit.
• Targets are verified read-only.
• Commands avoid secret output.
• Expected results guide decisions.
• Rollback has test evidence.

Need a safer development workflow?

Terry Hunt Dev helps teams turn deployment knowledge into tested operating procedures through DevOps consulting. Request a runbook review through the contact page using sanitized examples.