feat(servers): expose branch, auto-deploy and atomic deployment flags

[thdurante]

Summary

Adds five first-class deployment-configuration flags to dhq servers create and dhq servers update, so automation no longer has to drop to the generic dhq api escape hatch:

--branch  --auto-deploy  --atomic  --atomic-strategy  --atomic-retention

A shared serverDeploymentFlags helper backs both commands so they cannot drift apart. Only explicitly-supplied flags are sent, so an update never disturbs a setting the operator did not name. Booleans and retention reach the SDK as pointers: an omitted flag stays off the wire, an explicit --auto-deploy=false still serialises as false, and a zero retention never reaches the backend's >= 1 validation. Strategy and retention are validated locally before the project is resolved and the API client is built, so a malformed invocation fails offline with no credentials touched.

Companion API PR: deployhq/deployhq#1106 — corrects the published request schema this client depends on. Worth landing together: the spec currently types auto_deploy as string and omits the atomic fields entirely, so the CLI's (correct) request shape fails validation against the published document.

Resolves DHQ-691.

Behaviour verified against the Rails source

Rather than assume, each rule was traced to backend code:

Behaviour	Evidence
--branch "" unpins a server	IGNORE_PARAMS_ON_BLANK is credential-only (server_params.rb:7), so a blank branch is permitted and persisted; every consumer resolves it with .presence
--atomic locked after first deploy	ServerConcerns::Atomic#can_update_atomic? → deployments.first.nil?
retention >= 1	server.rb:103 numericality validation
strategies are exactly copy_release / copy_cache	servers_helper.rb:19-20; column defaults to copy_release
atomic silently stripped for non-atomic accounts	servers_controller.rb:683,698 — permitted only when atomic_deployments_allowed?; validate_atomic_allowed is guarded by if: :atomic_changed?, so it never fires

Two silent-failure modes now surfaced

Both were previously "succeeds with exit 0, changed nothing". Warnings go to stderr; stdout stays pure data.

1. Atomic requested but not applied. The create/update response is the read-back the docs asked operators to perform, so the CLI compares intent against the returned server instead of delegating to a reference doc an agent may never load. No extra request.
2. --branch on a grouped server. The backend resolves server_group.branch || server.branch || repository.branch, and grouped servers are excluded from auto-deployment entirely — so a branch stored on a grouped server never deploys. Rails hides the field in its UI; the API does not.

Test plan

• go build ./cmd/dhq/
• go vet ./...
• go test ./... — 871 passing (was 853 on main)
• go test -race ./... — 871 passing
• Local validation exercised against the real binary: invalid strategy and retention 0 / -1 return structured user_error / exit_code: 1 with recovery hints

Mutation-tested, not just green. Two regressions were introduced deliberately to confirm the new tests actually catch them:

• deleting both applyToCreate/applyToUpdate call sites previously left the entire suite green — it now fails
• disabling the Managed VPS --accept-cost billing gate now fails

Review round

Addressed on-PR feedback; all three threads resolved.

Reviewer	Finding	Outcome
Codex	Managed VPS examples in servers.md passed --json but omitted --accept-cost, so they hard-fail before creating anything	Fixed in 681f3bc — also corrected the pre-existing "My VPS" example carrying the same defect on main
CodeRabbit	blockNetwork writes called without synchronisation — data race	Skipped, refuted: the only goroutine is in SendTelemetry, invoked after cmd.Execute() returns; and every caller asserts require.Error, so cobra returns before PersistentPostRun and called is never written. -race -count=3 → 57 passed, no race
CodeRabbit	MD028 blank line between blockquotes	Skipped — nothing lints markdown in this repo (ci.yml runs golangci-lint only), and the two warnings are meant to render as separate blocks

The --accept-cost fix was verified against the built binary with credentials resolvable, so the run actually reaches the gate: without the flag it stops at "Managed VPS creation requires --accept-cost"; with it the request reaches the API.

Backward compatibility

• No change to public API response shape
• No change to existing CLI command output/behaviour when the new flags are absent
• pkg/sdk change is additive — five new fields on ServerCreateRequest/ServerUpdateRequest; no existing field altered

Documentation

• skills/deployhq/references/servers.md — flag table, both silent-failure warnings, unpinning, two-environment worked example
• skills/deployhq/SKILL.md — atomic gotchas in the always-loaded entry point, so an agent that never opens the reference still gets the irreversibility warning
• skill-evals/ — 5 new cases; also fixed an existing eval that could not fail for the footgun it guarded
• CHANGELOG.md

🤖 Generated with Claude Code

https://claude.ai/code/session_01Hibw5xsRNGDkYzr1hXsDQz

Summary by CodeRabbit

• New Features

  • Added server deployment settings for branch selection, automatic deployment, atomic deployments, strategies, and release retention.
  • Added SDK support for preserving explicitly provided false, empty, and zero values.
  • Added validation and warnings for unsupported strategies, grouped-server branch behavior, and unavailable atomic deployments.

• Documentation

  • Added command examples and guidance for configuring, verifying, and updating deployment settings.
  • Updated the unreleased changelog.

[linear]

DHQ-691

[coderabbitai]

Walkthrough

Changes

Server deployment configuration

Layer / File(s)	Summary
SDK deployment request contracts pkg/sdk/types.go, pkg/sdk/server_deployment_settings_test.go, pkg/sdk/integration_test.go	Server create and update requests now support optional branch, auto-deploy, atomic, strategy, and retention fields. Tests verify JSON nesting, explicit values, and omitted fields.
CLI flag validation and server wiring internal/commands/servers.go, internal/commands/servers_test.go	servers create and servers update register deployment flags, validate values before network access, apply explicit settings, default create atomic strategy to copy_release, and warn about unapplied settings.
Documentation and evaluation coverage CHANGELOG.md, skills/deployhq/SKILL.md, skills/deployhq/references/servers.md, skill-evals/deployhq/evals.json	Documentation and evaluations cover deployment flags, restrictions, grouped-server behavior, branch clearing, verification, and atomic deployment rules.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI as servers create/update
  participant Validation as deployment flag validation
  participant Request as ServerCreateRequest/ServerUpdateRequest
  participant DeployHQAPI
  CLI->>Validation: validate supplied deployment flags
  Validation->>Request: apply explicit deployment settings
  Request->>DeployHQAPI: create or update server
  DeployHQAPI-->>CLI: return server response
  CLI->>CLI: emit dormant or unapplied setting warnings

Loading

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change by identifying the new server deployment flags.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch thiago/dhq-691-expose-server-branch-auto-deploy-and-atomic-deployment

---

_{Comment @coderabbitai help to get the list of available commands.}

[thdurante]

@codex review this pr

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

pkg/sdk/server_deployment_settings_test.go (1)

16-34: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Move handler assertions to the test goroutine. require calls FailNow, which must run in the test goroutine. Record the method and decode error in each handler, then assert them after the client call. Replacing require with assert does not move the assertions out of the handler goroutine.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pkg/sdk/server_deployment_settings_test.go` around lines 16 - 34, Update
captureCreateBody and captureUpdateBody so their HTTP handlers only record the
request method and JSON decode error, without calling require or assert. After
each client call in the associated tests, assert the recorded method and decode
error from the test goroutine, preserving the existing request validation.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@internal/commands/servers_test.go`:
- Around line 28-39: Update blockNetwork to use sync/atomic.Bool for called,
storing true atomically in the transport callback and returning the atomic flag
rather than *bool. Adjust every called assertion to use Load(), add the
sync/atomic import, and preserve go vet and race-test compatibility.

In `@skills/deployhq/references/servers.md`:
- Around line 73-75: Fix the MD028 violation between the two blockquotes by
replacing the blank line with a non-blockquote separator, such as a normal
paragraph separator, so the validation-error and --branch warning blocks remain
distinct.

---

Nitpick comments:
In `@pkg/sdk/server_deployment_settings_test.go`:
- Around line 16-34: Update captureCreateBody and captureUpdateBody so their
HTTP handlers only record the request method and JSON decode error, without
calling require or assert. After each client call in the associated tests,
assert the recorded method and decode error from the test goroutine, preserving
the existing request validation.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: da085057-1fae-4cc6-a120-65f75fb8c7fa

📥 Commits

Reviewing files that changed from the base of the PR and between fc0524a and d816eab.

📒 Files selected for processing (9)

• CHANGELOG.md
• internal/commands/servers.go
• internal/commands/servers_test.go
• pkg/sdk/integration_test.go
• pkg/sdk/server_deployment_settings_test.go
• pkg/sdk/types.go
• skill-evals/deployhq/evals.json
• skills/deployhq/SKILL.md
• skills/deployhq/references/servers.md

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d816eaba8b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".