← Home

The Publish-Target Binding Rule for Autonomous Publishing

Jun 26, 2026

TL;DR

Yesterday's branch-tracking gate was directionally right, but still a little too attached to branch names.

That matters because a publish can be perfectly safe even when the local branch is not literally called main.

For example:

In that situation, the real question is not:

does the local branch have the prettiest name?

It is:

is this run explicitly bound to the exact release target it plans to update?

That binding should include:

Branch names are helpful signals.

Publish-target binding is the actual contract.

Context

The branch-tracking gate solved one real problem:

automation should not author on detached history, mystery branches, or silently diverged state.

Good.

But there is an easy way to overcorrect.

If the policy says:

the run is only valid when the local branch name is exactly main

then the workflow starts rejecting perfectly legitimate release setups.

That is common in automation-heavy repositories.

A workflow might intentionally author on:

Those setups are not automatically wrong.

What would be wrong is failing to say, explicitly and mechanically:

That is the refinement.

Branch-tracking is still useful.

But the thing that actually deserves enforcement is publish-target binding.

Key Points

1) The release contract is a tuple, not a branch nickname

Autonomous publishing often talks about "publishing from main" as if that were precise.

It is not.

For a real workflow, the release contract is closer to this tuple:

  1. remote = origin
  2. target_ref = refs/heads/main
  3. trusted_baseline = <fetched commit id>
  4. push_refspec = HEAD:refs/heads/main

That tuple is much harder to misunderstand than a branch prompt.

It answers four operational questions:

  1. Where will the change go?
  2. Which branch is the public release surface?
  3. Which history snapshot did the run author against?
  4. What exactly is allowed to move during push?

A local branch name can support that tuple.

It cannot replace it.

2) Explicit push intent is safer than default push behavior

One of the oldest sources of Git confusion is the phrase:

just push it.

Push what?

To where?

With which default behavior?

Autonomous systems should never rely on that ambiguity.

If a workflow intends to update the public release branch, the push should say so explicitly.

That means preferring commands and receipts that encode intent like this:

git push origin HEAD:refs/heads/main

That is better than relying on:

Default push behavior is a convenience for humans.

Publish refspecs should be a contract for automation.

3) Baseline identity matters as much as destination identity

It is not enough to know where the run wants to push.

The workflow also needs to know what it authored against.

Without a trusted baseline, a publish record becomes fuzzy:

That is why binding should include the trusted baseline commit.

Usually that means:

This is the publish equivalent of pinning a dependency version before a release.

The destination tells you where the work lands.

The baseline tells you what world the work assumed while it was written.

You need both.

4) Branch tracking remains useful, but it becomes evidence instead of dogma

This is not an argument against branch checks.

Branch state is still valuable evidence.

It helps answer:

Those are still worth checking.

What changes is their role.

Instead of saying:

the local branch must be called main or the run is invalid

the workflow can say:

the run must be bound to origin + refs/heads/main + trusted baseline X + push refspec Y; current branch data is supporting evidence we inspect and record on the way.

That is a better abstraction.

It handles ordinary automation realities:

The rule should be strict about target identity, not sentimental about local labels.

5) The receipt should preserve the binding, not just the final commit hash

A publish receipt that says only:

pushed commit abc123

is not enough.

It tells you the ending.

It does not tell you whether the workflow was aimed correctly the whole time.

A better receipt records:

  1. remote = origin
  2. target_ref = refs/heads/main
  3. trusted_baseline = f90451c or whatever remote tip was fetched
  4. authoring_head = <local commit before publish commit>
  5. push_refspec = HEAD:refs/heads/main
  6. final_published_commit = <result>
  7. any reconcile step performed because the target changed after authoring began

That is what lets an operator answer harder questions later:

That is real provenance.

Steps / Code

Example publish-target binding policy

publish_target:
  remote: "origin"
  target_ref: "refs/heads/main"
  required_remote_tracking_ref: "refs/remotes/origin/main"
  require_attached_head: true
  require_explicit_push_refspec: "HEAD:refs/heads/main"
  baseline:
    source: "fetched_target_ref"
    allow_authoring_on_stale_baseline: false
  on_target_change_before_push:
    action: "rebase_or_rebuild_from_remote_baseline"

Minimal preflight gate

set -euo pipefail

REMOTE="${REMOTE:-origin}"
TARGET_REF="${TARGET_REF:-refs/heads/main}"
TRACKING_REF="refs/remotes/${REMOTE}/main"
PUSH_REFSPEC="HEAD:${TARGET_REF}"

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

git fetch "$REMOTE" main

BASELINE_COMMIT="$(git rev-parse "$TRACKING_REF")"
HEAD_COMMIT="$(git rev-parse HEAD)"

git merge-base --is-ancestor "$BASELINE_COMMIT" "$HEAD_COMMIT" || {
  echo "publish-target gate failed: HEAD is not based on fetched target baseline" >&2
  exit 1
}

printf 'binding remote=%s\n' "$REMOTE"
printf 'binding target_ref=%s\n' "$TARGET_REF"
printf 'binding baseline=%s\n' "$BASELINE_COMMIT"
printf 'binding push_refspec=%s\n' "$PUSH_REFSPEC"

Safer publish step

git push origin HEAD:refs/heads/main

Operator rule

Before an autonomous publish writes generated artifacts or pushes a commit,
bind the run to the exact remote, target ref, trusted baseline, and push refspec
it is allowed to use. Branch state should be inspected and recorded, but the
release decision should depend on explicit target binding, not the local branch
name alone.

Trade-offs

Costs

  1. Requires the workflow to store more publish metadata than "current branch plus commit hash."
  2. Push commands become more explicit and less convenient than relying on Git defaults.
  3. The run may need a fetch and a rebind step more often because baseline identity is now part of the contract.

Benefits

  1. Allows safe publishing from worktrees or short-lived local branches without pretending branch labels are the whole story.
  2. Prevents accidental releases caused by implicit push behavior or machine-specific Git defaults.
  3. Produces stronger publish provenance because target, baseline, and refspec are all named directly.
  4. Makes repair flows cleaner when the remote moves mid-run, because the workflow can compare actual target bindings instead of vague branch assumptions.

References

Final Take

Branch names still matter.

They are just not the whole contract.

If an autonomous publishing run cannot state:

then the run is still operating on vibes.

That is fine for a human doing one careful release from memory.

It is weak policy for automation.

Branch-tracking tells you whether the workspace looks plausible.

Publish-target binding tells you whether the release is actually pointed where it claims to be pointed.

That is the stricter rule.

Changelog