Repository navigation
fix(agent): check the GitHub token can push before the agent runs (#801) - #1053
Conversation
A token can authenticate and read a repository while GitHub refuses every write: a classic PAT with no scopes still reads public repositories. Such a token passed clone and the whole agent run and failed only at the final push, so the work was lost (69 turns, $1.90 in the observed run). The orchestrator's preflight does not catch it because the REST API's permissions.push describes the user's role on the repository, not what the token may do. setup_repo now runs `git push --dry-run --no-verify` to a ref that does not exist, right after the clone and credential-helper setup. The dry run asks GitHub for the push service through the same credential helper as the final push, so it works for classic, fine-grained and App tokens without parsing scopes, and sends no ref update. --no-verify keeps a pre-push hook from the cloned repository from running. A refusal fails the task in seconds with PushCapabilityError, whose message starts "Token cannot push to <repo>" (the phrase the CDK error classifier maps to "Insufficient GitHub token scopes", non-retryable) and names the token type and the permission to add. Transient failures and egress blocks go through the existing setup classification. Read-only workflows (pr-review) never push and skip the check.
GHSA-fc5q-39xc-vjpf (updated 2026-11-17) covers every picomatch release through 4.0.7, the latest, so no version fixes it and security:deps fails on every branch. The locked copies (2.3.2, 4.0.5, 4.0.7) serve build, test and lint tooling only; no runtime dependency of cdk, cli or web reaches picomatch, so no Lambda bundle, the CLI or the console ships it, and the tooling matches only patterns from this repository's own configuration. #1052 accepts the same advisory as part of its dependency upgrade; whichever merges second keeps one entry.
Review of #1053 found cases where the first version failed a task that worked before, or named the wrong fix: - An empty repository: HEAD names no commit there, so pushing it failed before git contacted the remote. The probe is now a commit of the empty tree (git commit-tree), which every clone has; it writes one unreferenced object and leaves HEAD, the index and the tree alone. - A ref with the probe's name already on the remote made the dry run a non-fast-forward refusal and blocked every task on that repository. The refspec is now forced; a dry run sends nothing either way. - A 120 s timeout escaped as TimeoutExpired, classified "Build/tests didn't finish in time". It is now a retryable dependency_unreachable. - A rejected credential (401) got the scope remedy and a message saying the token can read the repository. It is now BLOCKED[auth_failure]: replace the token. An archived repository and SAML SSO or IP allow list refusals get their own message instead of the scope remedy. - The error quotes the stderr line that matched, not a warning git prints first, and each refusal emits an agent_blocked event. - _fail_setup_command is annotated NoReturn. Comments that misdescribed the classifier, the final push and the pre-push hook are corrected. Tests cover each case, four of them with real git (empty repository, existing ref, pre-push hook, nothing changed). SECURITY.md and the user guide name the check.
… names (#801) The second /review_pr found that the archived and SAML checks searched all of git's stderr, which carries the user and repository names: a scope-less token refused for user `samlee`, or on `acme/archived-notes`, got the SSO or archive message, and a 502 on such a repository became a permanent refusal. Transient failures now never reach the refusal checks, and GitHub's archive, SAML SSO and IP allow list messages are matched as whole phrases on remote: lines only. - The archived and organization-policy refusals no longer carry the "Token cannot push to" phrase, which the classifier titles "Insufficient GitHub token scopes" with a scope remedy. Two classifier patterns give them their own titles and remedies. - PushCapabilityError carries its cause, and the agent_blocked event follows it: an archived repository is not reported as the token's fault. - A timeout says one attempt timed out instead of claiming retries, and logs what git printed before it. - git's "returned error: 429" counts as transient (the clone too). - The quoted line hides the login of "denied to <user>"; "could not read username" and "Invalid username or token" count as a rejected credential; the fine-grained remedy names the token's repository access. - Comments corrected: an invalid token fails before the check, the probe commit is made, not found, in each clone, and the hook and 404 rationales. The user guide's way to tell this failure from preflight_failed works, the SECURITY.md row follows the pipeline order, and the picomatch reason names the docs dependency and the agent image's own copy. Tests cover each case, through the real retry loop and real git as well (the dry run reaches the remote; the hook test pins core.hooksPath).
|
I’d request changes before merging. Checking immediately after clone makes sense, and the 114 repository and shell tests passed for me on
GitHub also withdrew the picomatch advisory after this PR opened. I ran |
… scope (#801) From krokoko's review of #1053: - Setup added gh to git's credential helpers, but git asks every helper (system, global, local) in turn and takes the first answer: a saved GitHub login on a developer machine answered first, so the push check, and the final push, ran as that login. An empty local credential.helper now clears every inherited helper, URL-scoped ones included, before gh is added. - A repository-bound workflow that delivers an artifact clones for context and never pushes, but was checked. The rule the post-hooks use is now Workflow.delivers_repo_artifact, and setup skips the check by it; an unloadable workflow is still checked, as the post-hooks then open a PR. - A classic PAT needs `public_repo` for a public repository; `repo`, which grants every private repository its owner can reach, only for a private one, and either way the owner needs write access. The classifier carries the agent's token-specific fix into the remedy, so the console no longer shows fine-grained PAT advice for an App token. - GitHub withdrew GHSA-fc5q-39xc-vjpf, and security:deps passes without the picomatch entry: osv-scanner.toml is back to main's.
|
@krokoko thanks for the review. All four points are addressed in 2ac5526.
Reproduced: with a saved-login helper in the global git config,
The delivery rule is now one property,
For a classic PAT, the refusal now says For the console: the classifier now passes the agent's token-specific fix through as
A
Confirmed the withdrawal, and Locally on 2ac5526: Not verified: none of this has run against GitHub with real classic, fine-grained or App tokens. |
Conflicts: - agent/src/pipeline.py: main (#1052) made the repo-bound artifact rule use resolved_requires_repo; this branch moved the rule into Workflow.delivers_repo_artifact, which the push preflight shares. Kept the shared property and gave it main's semantics. - cdk/src/handlers/shared/error-classifier.ts: kept main's PR_FROM_FORK pattern and this branch's organization-policy and archived patterns. - agent/tests/test_repo.py: kept both new imports.
|
Thanks for the fixes, Nizar. I checked
I also found a smaller console issue. With a long |
…PR strategy (#801) From krokoko's second review of #1053: - A url.<base>.pushInsteadOf rule rewrote the push URL (to SSH) while the fetch URL stayed HTTPS, so the push preflight and the final push could use the developer's SSH key, not the task's token. Setup now sets an explicit HTTPS push URL, which pushInsteadOf does not rewrite, reads back the effective push URL and stops when an insteadOf rule still rewrites it. - The credential-helper reset cleared helpers for every host. It is now credential.https://github.com.helper, so a login for another host in the same checkout keeps working. - Git's output is redacted before it is shortened (the timeout warning, the refusal excerpt, the setup failure snippet): keeping the last 500 characters of a 519-character App token removed the prefix the redactor matches and left the rest in the warning. - A writeable workflow whose ensure_pr step uses the resolve strategy only looks up its PR. Workflow.ensure_pr_strategy is now the rule both the post-hooks and setup read, and setup skips the check for resolve. - The task record keeps 1,000 characters of the error. With a long owner/repo and a token of no known type the message was 1,373, so the sentence the classifier matches was cut and the console showed the generic PR and Issues remedy. The remedies now say "the repository" instead of repeating its name: the longest message is 992 characters. Tests: pushInsteadOf and insteadOf with real git, the scoped reset against a second host, the 519-character token through the timeout path, a resolve-strategy workflow, and the longest refusal both measured in Python and classified, cut at 1,000, in the CDK suite. The new tests fail against 8e20a76 where they cover a defect.
setup_reponow checks, right after the clone, that GitHub lets the token push to the repository, and fails the task in seconds when it does not. Before, a token that could read but not write passed clone and the whole agent run and failed only at the final push, losing the work: in the observed run, 69 turns and $1.90, most of it spent working around the failed push.Area
cdk— infrastructure, handlers, constructsagent— Python runtime / Docker imagecli—bgagentclientdocs— guides or design sources (docs/guides/,docs/design/)tooling— rootmise.toml, scripts, CI workflowsCDK: error-classifier patterns for the agent's refusals (
cdk/src/handlers/shared/error-classifier.ts) and their tests; no construct, stack or IAM change. Theosv-scanner.tomlentry of an earlier commit was removed again (see below), so the net diff has no tooling change.Related
Closes #801. Relates to #802 (same observed run reported
successwith no PR): this makes that condition rare but does not fix the finalize path.Changes
The check; a
picomatchadvisory entry (since removed); two rounds of fixes from/review_pr(six review agents each); two rounds of fixes from krokoko's reviews; and merges ofmain.Why the existing checks miss it. The orchestrator's preflight (
cdk/src/handlers/shared/preflight.ts) readspermissions.pushfromGET /repos/{repo}, falling back to GraphQLviewerPermission. Both describe the user's role on the repository, not what the token may do, so a classic PAT with no scopes reportspush: true. Such a token also clones a public repository, since reads need no scope.The check (
_preflight_push_capabilityinagent/src/repo.py, called after the remote and credential helper are configured, before branch setup):X-OAuth-Scopesheader for a fine-grained PAT, so a scope check would have to special-case it<probe>is a new commit of the empty tree (git commit-tree), notHEADHEADnames no commit in a clone of an empty repository, and pushing it fails before git contacts the remote. Git knows the empty tree without storing it, so making the probe writes one unreferenced commit object and leavesHEAD, the index and the working tree alone+)--no-verifycore.hooksPathor a git template; a clone copies no hooks)coding/pr-review-v1); repository-bound workflows that deliver an artifact (Workflow.delivers_repo_artifact); and workflows whoseensure_prstep uses theresolvestrategy, which only look up the existing PR (Workflow.ensure_pr_strategy). Both are now the rules the pipeline's post-hooks and setup share. An unloadable workflow is checked, since the post-hooks then fall back to opening a PRurl.<base>.pushInsteadOfrule in the machine's git config rewrites the push URL (to SSH, say) while the fetch URL stays HTTPS, so the check and the final push would use the developer's SSH key. Setup sets an explicit push URL, whichpushInsteadOfdoes not rewrite, reads back the effective push URL, and stops with an error when aninsteadOfrule still rewrites itgithub.comcredential helpers are clearedgh, and the check (and the final push) would have run as that login. Setup sets an empty localcredential.https://github.com.helperbefore addinggh. That clears every helper read before it for github.com only, so a login for another host in the same checkout keeps workingOutcomes. Failures that look transient (5xx, 429, timeouts, DNS) are never read as refusals. Of the rest, GitHub's archive and organization-policy messages are matched as whole phrases on
remote:lines only, so a user or repository name (samlee,acme/archived-notes) cannot pick the cause.Permission to … denied,Write access to repository not granted, 403, 404,Repository not foundToken cannot push to <repo>, naming the token type (from its documented prefix) and the fix:public_repofor a public repository orrepofor a private one (classic;repogrants every private repository the owner can reach), repository access and Contents Read and write (fine-grained), Contents write and installation (App), both otherwise; for a personal token, that its owner needs write access. A 404 counts because the clone has just fetched the repositoryAuthentication failed,Invalid username or token, no credentialBLOCKED[auth_failure] (resource: <repo>): replace the token. An invalid token fails earlier (orchestrator preflight andgh repo cloneboth send it), so this is a token revoked after the clone, or none suppliedThis repository was archived so it is read-onlyRepository <repo> is archived on GitHub, so it is read-only… enabled or enforced SAML SSO,… IP allow list …GitHub organization policy blocks pushes to <repo>, naming the policy and its fixBLOCKED[dependency_unreachable], retryable, saying one attempt timed out (run_cmd_with_backoffdoes not retry a timeout)dependency_unreachable,egress_denied, or the redacted git errorAll non-retryable. Each refusal emits an
agent_blockedevent whose kind and detail follow its cause (auth_failure, orunknown_environmentalfor an archived repository, which no token change fixes). The error quotes the stderr line that matched, redacted withredact_secretsbefore it is shortened (so is every excerpt of git's output: a cut could remove the prefix the redactor matches), with the login ofdenied to <user>replaced by<token user>; the token never enters the message, the argv or.git/config. The remedies say "the repository" rather than repeatowner/repo, so the longest message (a 140-characterowner/repo, a token of no known type, a full excerpt) is 992 characters and fits the 1,000 the task record keeps; the sentence the classifier matches is never cut._fail_setup_commandis annotatedNoReturn, so the check cannot fall through to a passing setup. git'sThe requested URL returned error: 429now counts as transient (agent/src/shell.py), which the clone benefits from too.The classifier carries the agent's fix into
error_classification.remedy(the API builds it intoTaskDetail; the web console's failure banner showsdescriptionandremedy), so the console gives the fix for the token type, not the generic fine-grained-PAT remedy. The orchestrator's preflight uses the sameToken cannot push tophrase, but its message also carries theINSUFFICIENT_GITHUB_REPO_PERMISSIONScode, which classifies first as "Insufficient GitHub permissions" and keeps its remedy.Docs:
agent/README.md(the check, a table of its outcomes, the credential reset, andpublic_repovsrepofor a classic PAT),docs/design/SECURITY.md(a row in the policy table, after hydration),docs/guides/USER_GUIDE.md(how to tell this failure frompreflight_failed: thePushCapabilityError:prefix), mirror regenerated.picomatch(GHSA-fc5q-39xc-vjpf). An earlier commit accepted this advisory inosv-scanner.tomlwhile it had no fixed release. GitHub withdrew it on 2026-11-18, andsecurity:depspasses without the entry, so the entry is removed andosv-scanner.tomlis unchanged frommain.Testing
On the committed tree (macOS, arm64):
mise run build: passes (agent 3,114 tests, cdk 7,899, cli 1,472, web 237) and rewrites no file.security:sast:masking,security:sast:range(0 findings) andsecurity:secrets: pass.agent/tests/test_repo.py:TestPushCapabilityPreflight: the push URL pinned to HTTPS before the check, a rewritten push URL stopping setup, a writeableresolve-strategy workflow skipped; argv, forced probe refspec and a real token absent from it; timeout value; ordering against the credential helper, branch setup and the PR-iteration and stacked-child fetches; read-only skip (no probe made) and its tie to the shipped workflows; a repository-bound artifact workflow is skipped,default/agent-v1with a repository and an unloadable workflow are checked; the credential-helper reset runs beforeghis added; passes for fine-grained and classic tokens; each refusal shape and its message and live event (403, 404, fine-grained wording, 401, archived, SAML, IP allow list); names containingsamlorarchivedin the user or repository, on refusals and on a 502; the remedy per token type; the quoted line and the hidden login; redaction; timeout, 429, transient, egress and other failures; a failed probe commit.TestPushPreflightRetries(2), through the real retry loop: a refusal takes one attempt and no sleep, a 502 three attempts.TestPushPreflightAgainstRealGit(real git, local bare remote): a globalpushInsteadOfleaves the push URL on HTTPS and a globalinsteadOfmakes setup stop; thegithub.comhelper reset leaves a second host's login working; with a saved-login helper in the global config (generic and URL-scoped) and a stand-ingh, onlyghanswers for github.com (without the reset the saved login answers); leaves the remote's refs,HEAD, the working tree and.git/configunchanged; reaches the remote (fails when it is missing); passes on an empty repository; passes when the remote has a divergent ref with the probe's name; does not run a pre-push hook that a plain dry run does run.agent/tests/test_shell.py: git's 429 is transient.TestPushPreflightRedaction: a 519-character App token through the timeout warning stays redacted (fails against8e20a76).TestPushRefusalFitsTheTaskRecord: the longest refusal is 992 characters.error-classifier.test.ts: the longest refusal, cut at 1,000 as stored, still gets the agent's fix (the message at8e20a76was 1,373 characters and lost it); the persisted messages, printed from the agent code, classify as in the table, all non-retryable; for classic, fine-grained, App and unknown tokens and a repository with a dot in its name, the remedy is the agent's fix; the orchestrator's message keeps its own;toTaskDetailgives the console the App token's fix.git push --dry-runto a public GitHub repository the account may not write was refused with403 Permission to … denied, whilegit ls-remoteon it succeeded.Not verified: a task on a deployed stack; the dry run against GitHub with a real scope-less classic PAT, a fine-grained PAT, an App token, an archived repository or an SSO or IP-allow-list organization (those stderr shapes follow GitHub's documented messages, not live runs).
Follow-ups worth filing: make the orchestrator's preflight test the token rather than the user's role, which would catch this before compute starts; count a timeout as a transient attempt in
run_cmd_with_backoff, which the clone needs too.Acknowledgment
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.