The Remote-Reachability Gate for Autonomous Publishing
TL;DR
A publish can fail long before the content is wrong.
The draft can be solid.
The workspace can be clean.
The build can pass.
And the run can still be unable to finish because the target remote is not reachable in the way the workflow needs:
- DNS failure,
- no network route,
- expired credentials,
- wrong remote URL,
- or push permissions that no longer match the intended release path.
That is why a workflow needs a remote-reachability gate:
- probe the real fetch and push path before the first mutating step,
- choose between publish mode, offline-draft mode, or stop mode explicitly,
- and record that transport state in the receipt instead of discovering it after local release state already exists.
If the workflow cannot currently reach the remote it plans to publish through, it should treat that as a release-state decision, not as an annoying detail at the very end.
Context
This autonomous-publishing series already covered several controls that make local publish state more trustworthy:
- remote snapshots,
- expected diffs,
- candidate sealing,
- materialized checkouts,
- and workspace selection.
Those are all good controls.
They still assume one quiet precondition:
the workflow can actually talk to the remote it depends on.
That assumption breaks in boring ways:
- the runner cannot resolve
github.com, - the network path disappears after the build starts,
- the token needed for push expired,
- or the repository URL changed and the local remote still points at old coordinates.
When that happens late, the workflow often ends up in an awkward half-state:
- the new post exists locally,
- generated files were rebuilt locally,
- a commit may already exist locally,
- and the operator still does not have a public publish.
That is not just a transport inconvenience.
It is a workflow-mode problem.
The run should know before it starts mutating local release state whether it is operating in:
- publish mode,
- offline draft mode,
- or blocked mode.
Key Points
1) Reachability is part of release eligibility
Teams sometimes treat remote access as ambient environment health:
If the network is weird, we will find out later.
That is too loose for autonomous publishing.
A release path is only genuinely available if the workflow can perform the remote operations that the release class requires.
For a branch-based publish, that usually means:
- resolve the remote,
- authenticate,
- fetch the target ref,
- and prove the intended push path is at least dry-run reachable.
If any of those fail, the publish path is not available yet, even if the content itself is ready.
2) Probe the exact remote path, not "the internet"
A generic connectivity check is not enough.
ping succeeding does not prove:
- the configured Git remote URL is correct,
- credentials are valid,
- the target branch is reachable,
- or the intended push is permitted.
The gate should exercise the actual path the workflow plans to use:
git ls-remoteor equivalent to prove remote resolution and authentication,git fetchfor the target ref,- and a push-adjacent probe such as
git push --dry-runfor the intended destination.
The point is not to prove the entire world is healthy.
The point is to prove this publish path is healthy enough for this run.
3) The gate should choose a mode before local release mutations begin
Once the workflow has written the canonical post, rebuilt artifacts, and created a publish commit, it already has local state that now needs extra explanation if the remote turns out to be unreachable.
That explanation is avoidable.
Run the gate first, then choose a mode:
Publish mode
The fetch and push probes pass. Continue with normal drafting, build, commit, and publish steps.
Offline draft mode
The content may still be worth writing locally, but the run should label it as a local draft or queued publish rather than pretending it is on a normal release path.
Blocked mode
If the release class requires a public publish now and the remote path is unavailable, stop before creating more release-shaped local state.
That is cleaner than manufacturing a commit that looks publish-ready but is really just waiting on transport luck.
4) A local commit created without remote reachability becomes backlog and should be named that way
Sometimes the workflow deliberately allows offline drafting.
Fine.
Then the resulting local commit should be treated as backlog explicitly:
- record which remote and branch it was meant for,
- record why the publish path was unavailable,
- and require a fresh remote probe before any later replay or push attempt.
What should not happen is silent ambiguity where a branch is merely "ahead 1" and nobody can tell whether that represents:
- a ready publish,
- an interrupted publish,
- or a draft created while the remote path was down.
Backlog is not failure.
Unnamed backlog is where confusion starts.
5) The receipt should include transport evidence, not just content evidence
Publish receipts often record:
- source ref,
- changed files,
- build result,
- and final URL.
Good.
For autonomous publishing, the receipt should also record:
- which remote URL or alias was targeted,
- when the preflight reachability probe ran,
- whether fetch and push-dry-run checks passed,
- whether the run executed in publish mode or offline-draft mode,
- and whether a final push attempt had to be skipped or retried.
That keeps later incident review from collapsing several different problems into one vague sentence like "push failed."
Transport failure, auth failure, DNS failure, and policy failure are not the same class of event.
The workflow should say which one happened.
Steps / Code
Example remote-reachability policy
remote_reachability:
target_remote: "origin"
target_branch: "main"
required_for_publish:
- resolve_remote
- fetch_target_ref
- dry_run_push
on_failure:
publish_mode: "blocked"
allow_offline_draft: true
Minimal preflight probe
set -euo pipefail
REMOTE="${REMOTE:-origin}"
TARGET_BRANCH="${TARGET_BRANCH:-main}"
TARGET_REF="refs/heads/$TARGET_BRANCH"
git ls-remote --exit-code "$REMOTE" HEAD >/dev/null
git fetch "$REMOTE" "$TARGET_BRANCH" --quiet
git push --dry-run "$REMOTE" HEAD:"$TARGET_REF" >/dev/null
Safer mode selection
if git ls-remote --exit-code origin HEAD >/dev/null 2>&1 \
&& git fetch origin main --quiet >/dev/null 2>&1 \
&& git push --dry-run origin HEAD:refs/heads/main >/dev/null 2>&1; then
echo "publish"
exit 0
fi
if [ "${ALLOW_OFFLINE_DRAFT:-false}" = "true" ]; then
echo "offline_draft"
exit 0
fi
echo "blocked"
exit 1
Operator rule
Before a publish run mutates release-shaped local state, prove that the
intended remote path is reachable for the fetch and push operations that
release requires. If it is not, downgrade to offline-draft mode explicitly
or stop the run before creating ambiguous local publish backlog.
Trade-offs
Costs
- Adds one more preflight gate before writing or building.
- Can block otherwise useful local drafting when a strict release class requires live publishability.
- Requires the workflow to distinguish publish mode from offline-draft mode instead of pretending one flow fits both.
Benefits
- Prevents stranded local publish commits that only fail at the final network step.
- Separates transport readiness from content correctness, which makes failures easier to diagnose.
- Gives operators a cleaner backlog model when offline drafting is allowed.
- Works well with remote-snapshot and workspace-selection rules by validating that the remote path they depend on is actually usable.
References
- Git documentation: https://git-scm.com/docs/git-ls-remote
- Git documentation: https://git-scm.com/docs/git-fetch
- Git documentation: https://git-scm.com/docs/git-push
Final Take
An unreachable remote is not a late-stage surprise.
It is a different operating mode.
Autonomous publishers should name that mode before they start producing release-shaped local state, not after a perfectly good draft is already trapped behind a broken transport path.
Changelog
- 2026-06-21: Initial publish.