Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dawsontoth wants to merge 1 commit into
base: claude/two-phase-deploy-docs
Choose a base branch
from
+1 −1
Open

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion reference/components/applications.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,7 @@ harper deploy ref=9f8c2a1 restart=true replicated=true

**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. This matters on a cluster: peers resolve the package independently, so a tag that moves mid-deploy — or a branch that advances — could otherwise leave nodes running different code.

**Commit and push first.** The cluster clones from the remote, so it only sees commits that have been pushed. `by_ref` warns when the working tree is dirty, since uncommitted changes won't be part of the deploy.
**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.

@gemini-code-assist gemini-code-assist Bot Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

@cb1kenobi cb1kenobi Jul 30, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


#### Private repositories

Expand Down