FACTUAL ACTIVITY RECORD · An activity record based on work that took place
Adding an authentication preflight for GitHub remote operations
Checking CLI auth, Git credential setup, and a live remote read before relying on cached tracking data
Purpose
Local tracking information made main appear current, while actual pull and ls-remote operations were failing on GitHub authentication. Work started in that state, and after authentication was repaired, a direct remote read showed that remote main had advanced beyond local state. Cached tracking information alone could not confirm that the working base was current.
The CEO asked for authentication checks before reading or updating the GitHub remote and for reauthentication before retrying when credentials were invalid. The procedure had to be reflected across agents, Skills, command rules, and operating documentation so work would not continue from stale tracking information when the remote could not actually be read.
Implementation
The investigation separated two conditions: invalid GitHub CLI authentication and Git HTTPS not being configured to use the CLI credential helper. After reauthentication and credential-helper setup, a direct read of remote main succeeded. To avoid repeating those checks manually, scripts/ensure-github-git-auth was added at the repository root.
The wrapper accepted no arguments and checked three stages in order: GitHub CLI authentication, credential-helper setup for Git, and a direct read of remote main. Authentication and remote-read output were discarded so tokens and credentials were not displayed. A failed check stopped with exit code 1 and recovery instructions, while any argument was rejected with exit code 2. The wrapper did not perform login automatically; an operator restored authentication and then reran the preflight.
#!/usr/bin/env bash
set -euo pipefail
if [ "$#" -ne 0 ]; then
echo "usage: scripts/ensure-github-git-auth" >&2
exit 2
fi
if ! gh auth status --hostname github.com >/dev/null 2>&1; then
echo "error: GitHub CLI authentication is missing or invalid." >&2
exit 1
fi
gh auth setup-git --hostname github.com >/dev/null
if ! git ls-remote --exit-code origin refs/heads/main >/dev/null 2>&1; then
echo "error: git cannot read origin/main with the current GitHub credentials." >&2
exit 1
fi
echo "GitHub CLI and git remote authentication are ready."The implemented wrapper also included reauthentication and credential-helper recovery steps in its failure messages. The operating rule required the preflight before git fetch, git pull, git push, git ls-remote, and gh pr. A failure prohibited continuing from cached origin/main; work resumed only after reauthentication and a successful preflight.
AGENTS.mdanddocs/operating-model.mdadded GitHub Auth Preflight as a software-delivery stage..agents/skills/software-delivery/SKILL.mdadded a gate that ran the preflight before remote operations and completed reauthentication before branch creation or delivery continued..agents/skills/pr-review/SKILL.mdrequired the same preflight when review fell back from a connector to the CLI and treated failure as a blocker instead of reviewing from cached tracking information..codex/agents/full-stack-engineer.tomland.codex/agents/pr-reviewer.tomlreceived the same failure boundary, adapted to implementation and review responsibilities..codex/rules/organization.rulesadded ordinary preflight and repair entries only for the argument-free wrapper, read-only authentication status, and credential-helper setup..codex/rules/README.mdanddocs/setup.mdsynchronized the wrapper flow, reauthentication steps, and the constraint against using stale tracking information.
Verification confirmed that the wrapper stopped with an authentication failure in a restricted sandbox that could not access the operating-system credential store. The same wrapper succeeded at an execution boundary with credential-store access, proving that the authenticated CLI and Git could read remote main. Shell syntax, every Custom Agent TOML file, and whitespace errors in the diff were also checked.
The CEO defined the scope for integrating authentication checks and reauthentication into operations. A general-purpose main AI investigated the cause, restored authentication, implemented the change across ten files, and ran the checks. Full-Stack Engineer and PR Reviewer were configuration targets and did not participate in the Activity's implementation.
What was confirmed
Verification results
A single wrapper combined CLI authentication, credential-helper setup, and a direct read of remote main. The operating boundary to stop on failure, reject stale tracking information, recover credentials, and rerun the preflight was consistent across configuration, two Skills, two agent definitions, command rules, and operating documentation. The wrapper did not automate login itself.
The wrapper stopped when the restricted sandbox could not access the credential store and succeeded at an execution boundary where the store was available. This confirmed that an environment without usable authentication was not treated as ready and that the failure was detected before relying on a remote read.
Shell syntax, every Custom Agent TOML file, and whitespace errors in the diff all passed their checks. A final check after the change was incorporated also passed the preflight and confirmed that the GitHub CLI and Git could read the remote. Command-rule entries were defined, but a policy evaluator was not run to verify their allow decisions.
The verified wrapper was fixed to github.com, origin, and refs/heads/main. Alternate hosts, remote names, default branches, and distinct handling for network failure, service outage, or insufficient permission were not tested.
Basis for completion
The Activity was complete when the authentication preflight and recovery boundary were consistent across the wrapper and operating entry points, the wrapper stopped without usable credentials and read the remote when credentials were available, and the shell, TOML, and diff checks succeeded.