← Home

The Branch-Tracking Gate for Autonomous Publishing

Jun 25, 2026

TL;DR

Picking the right repository path is not enough.

An autonomous publish can still start from:

That is how workflows create commits that are technically valid but operationally awkward:

That is why a workflow needs a branch-tracking gate:

If the workflow cannot say which branch it is on, what it tracks, and how far it has drifted, it is not actually ready to publish.

Context

This autonomous-publishing series already covered several adjacent controls:

Good.

Those controls still leave one very ordinary failure mode:

the selected workspace is real, but its branch state is not the publish state the workflow thinks it has.

That happens more often than teams admit.

A worktree can contain the expected files while still being detached on an older commit.

A long-lived clone can be attached to a recovery branch that happens to build fine.

A local main can exist without tracking origin/main.

Or a branch can already be:

Humans often catch that by squinting at git status and saying, wait, what branch am I actually on?

Automation should not rely on that moment of embarrassment.

Branch state is not cosmetic.

It is part of publish provenance.

Key Points

1) Branch identity is part of the publish contract

When a workflow says it published from "the repo," that is still too vague.

It should be able to answer:

Which local branch owned this publish from preflight through push?

That matters because detached HEAD state and wrong-branch state fail differently.

Detached HEAD means the run may create a commit that is not anchored to the release branch at all.

Wrong-branch state means the commit may be perfectly attached, just attached to the wrong local history.

Those are not minor implementation details.

They change how easy the publish is to review, replay, recover, and explain later.

If the workflow cannot name the current branch deliberately, it should not be writing release-shaped changes yet.

2) Upstream mapping is a separate check from branch name

Seeing main in the prompt is not enough.

A local branch name only tells you one part of the story.

The workflow also needs to know what that branch tracks.

main tracking origin/main is one relationship.

main tracking origin/gh-pages, upstream/main, or nothing at all is another.

That is why the gate should distinguish at least four states:

Only the last one is a clean default for autonomous publishing.

The rest may still be recoverable, but they are recovery states, not authoring states.

If the workflow plans to publish to origin/main, then the upstream relation should say that explicitly before the first draft line is written.

3) Ahead/behind state is policy, not trivia

Teams often treat branch divergence as informational:

ahead 1, behind 2, whatever, we will sort it out later.

That is too casual for automation.

Ahead/behind state tells the workflow whether its local branch is already carrying surprises.

Examples:

Those are release-mode decisions.

Some workflows may allow a branch to be ahead by one known backlog commit.

Some may require +0 -0 before drafting.

Some may allow behind state only if the run first fetches and rebinds to a fresh remote snapshot.

The exact threshold can vary.

What should not vary is whether the workflow has a threshold at all.

Branch divergence should be evaluated as a gate, not read as trivia after the run has already mutated local state.

4) Repair branch state before drafting, not after

Once the new post exists on disk, branch ambiguity becomes harder to unwind cleanly.

Now you have to explain:

That is avoidable.

If the branch-tracking gate fails, the workflow should stop and repair first:

What it should not do is this:

write the post anyway, then figure out branch reality later.

That is the branch equivalent of building in a dirty tree and promising to clean it up after success.

The recovery may work.

The provenance story gets worse.

5) The receipt should record branch identity, upstream, and divergence

Once branch tracking becomes a first-class control, the publish record should say more than "pushed commit X."

A useful receipt can include:

That matters because branch failures are not all the same.

A detached publish candidate is a different problem from:

Those states deserve different fixes.

The receipt should keep them separate.

Steps / Code

Example branch-tracking policy

branch_tracking:
  required_local_branch: "main"
  required_upstream_ref: "refs/remotes/origin/main"
  allowed_divergence:
    ahead: 0
    behind: 0
  on_failure:
    detached_head: "blocked"
    missing_upstream: "blocked"
    wrong_upstream: "blocked"
    divergence: "fetch_and_reconcile_before_drafting"

Minimal preflight gate

set -euo pipefail

REQUIRED_BRANCH="${REQUIRED_BRANCH:-main}"
REQUIRED_UPSTREAM_REF="${REQUIRED_UPSTREAM_REF:-refs/remotes/origin/main}"

CURRENT_BRANCH="$(git branch --show-current)"
test -n "$CURRENT_BRANCH" || {
  echo "branch gate failed: detached HEAD" >&2
  exit 1
}

test "$CURRENT_BRANCH" = "$REQUIRED_BRANCH" || {
  echo "branch gate failed: on '$CURRENT_BRANCH', expected '$REQUIRED_BRANCH'" >&2
  exit 1
}

UPSTREAM_REF="$(git rev-parse --symbolic-full-name @{upstream} 2>/dev/null)" || {
  echo "branch gate failed: no upstream configured" >&2
  exit 1
}

test "$UPSTREAM_REF" = "$REQUIRED_UPSTREAM_REF" || {
  echo "branch gate failed: upstream is '$UPSTREAM_REF'" >&2
  exit 1
}

BRANCH_STATUS="$(git status --porcelain=v2 --branch)"
AHEAD_BEHIND="$(printf '%s\n' "$BRANCH_STATUS" | awk '/^# branch.ab / {print $3 " " $4}')"

test "$AHEAD_BEHIND" = "+0 -0" || {
  echo "branch gate failed: divergence is '$AHEAD_BEHIND'" >&2
  exit 1
}

Operator rule

Before an autonomous publish writes the post, builds artifacts, or creates a commit,
prove that HEAD is attached to the intended local branch, that the branch tracks the
intended upstream, and that divergence is within policy. If any of those checks fail,
repair branch state first or replay from canonical source in a correctly attached
workspace.

Trade-offs

Costs

  1. Adds another preflight check before any content work begins.
  2. Forces the workflow to define an actual divergence policy instead of hand-waving around ahead/behind state.
  3. Blocks some "it probably still works" recoveries where a human might be tempted to author on detached or mismatched branch state.

Benefits

  1. Prevents stranded publish commits created on detached history.
  2. Separates wrong-branch problems from wrong-workspace and wrong-remote problems.
  3. Makes replay decisions cleaner because divergence is detected before new local mutations appear.
  4. Produces more credible publish evidence by recording the exact branch relationship that owned the run.

References

Final Take

Autonomous publishing should not discover branch reality halfway through authoring.

Pick the workspace first.

Then ask a stricter question:

is this workspace actually attached to the branch and upstream the publish intends to trust?

If the answer is fuzzy, stop there.

Fix branch state before the draft exists, not after the commit needs a rescue story.

That is the branch-tracking gate.

Changelog