docs(deploy): document by_ref's unpushed-commit warning

[dawsontoth]

Documents the second half of by_ref's pre-deploy safety check, added in harper#1850.

What changed

reference/components/applications.md previously said by_ref warns only when the working tree is dirty. It now warns in both directions, so the docs cover both:

• uncommitted changes — they won't be part of the deploy, and
• a commit that isn't on any remote branch — the cluster clones from the remote, so it can't fetch that commit at all.

Also notes the practical gotcha: the second check reads your local remote-tracking refs, so a stale view can warn about a commit you did in fact push. The fix is git fetch, and saying so here saves someone a confusing debugging detour.

Why it matters

The unpushed-commit case is the more damaging of the two. A dirty tree merely omits your latest edits; an unpushed commit means peers cannot resolve the reference at all, which surfaces as a cluster-wide deploy failure rather than a quietly stale build.

Review notes

• One line changed, in the by_ref section of the applications reference.
• Stacked on #599 (claude/two-phase-deploy-docs) rather than main. This branch is a strict superset of that one, so targeting main would have re-shown all ~389 lines of docs(deploy): two-phase deploy_component, revert_component, stage/activate CLI (draft) #599's still-unmerged content. With this base the diff is just the single commit that's actually new. GitHub will retarget this to main automatically once docs(deploy): two-phase deploy_component, revert_component, stage/activate CLI (draft) #599 merges — happy to repoint it sooner if you'd rather review them independently.
• Depends on harper#1850, which is still open. The warning text describes behavior that ships with that PR.

[gemini-code-assist]

Code Review

This pull request updates the documentation for by_ref deployments to explain that it now warns when the commit being deployed is not on any remote branch, in addition to warning about a dirty working tree. The reviewer suggested adding a <VersionBadge> to denote this behavior change, as prescribed in the repository's guidelines.

[gemini-code-assist]

When documenting behavior changes to an existing surface (such as the new unpushed-commit warning for by_ref), please include a to denote the change, as prescribed in the repository's guidelines.

Example:
Commit and push first. The cluster clones from the remote, so it only sees commits that have been pushed. by_ref warns in both directions: when the working tree is dirty (those changes won't be part of the deploy) and when the commit being deployed isn't on any remote branch (the cluster won't be able to clone it). The second check reads your local remote-tracking refs, so run git fetch if you get it for a commit you know you pushed.

References

1. Use the <VersionBadge type="changed" version="vX.Y.0" /> format when documenting behavior changes to existing surface, as prescribed in the repository's guidelines.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-617

This preview will update automatically when you push new commits.

[cb1kenobi]

Medium: the adjacent SHA-pinning guarantee (line 163) is not absolute, and this PR doesn't flag the gap

The unpushed-commit warning added here is accurate to warnIfCommitNotPushed in harper#1850 (bin/cliOperations.ts) — it checks git branch -r --contains <committish>, i.e. local remote-tracking refs, and the git fetch advice matches the code's own comment.

But the sentence right above this one (line 163) states unconditionally: "A reference is pinned to a SHA, not to the name you typed. Tags and branches are resolved locally and the full commit SHA is what ships." That's only true when resolveGitCommittish() can resolve the ref locally. Its catch branch does the opposite:

try {
  return runGit(['rev-parse', `${refStr}^{commit}`]);
} catch {
  // Not resolvable locally (e.g. a ref that only exists on the remote). Pass it through
  // and let the cluster resolve it — losing the pin, ...
  return refStr;
}

So a ref=<branch-or-tag-name> that isn't fetched locally (e.g. a teammate's remote-only branch) is deployed unpinned — the raw mutable name, not a SHA — which is exactly the cluster-divergence hazard line 163 says by_ref prevents. This PR is a good place to add that caveat, since it's already revisiting this paragraph for the sibling unpushed-commit warning: e.g. "...full commit SHA is what ships when the ref resolves locally; an unresolvable ref (one that exists only on the remote) is passed through unpinned by name instead."

—
Generated by Barber AI