From 62b03ca03323fe7cfabe893c01bd8b77fb31d5cb Mon Sep 17 00:00:00 2001 From: bgagent Date: Tue, 17 Nov 2026 16:25:09 -0600 Subject: [PATCH 1/6] fix(agent): check the GitHub token can push before the agent runs (#801) 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 " (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. --- agent/README.md | 4 + agent/src/repo.py | 124 +++++++++ agent/tests/test_repo.py | 254 ++++++++++++++++++ .../handlers/shared/error-classifier.test.ts | 16 ++ 4 files changed, 398 insertions(+) diff --git a/agent/README.md b/agent/README.md index fbfae525b..5e41eb38d 100644 --- a/agent/README.md +++ b/agent/README.md @@ -54,6 +54,10 @@ Set an expiration (90 days recommended) and store it in Secrets Manager the same | Org has not opted in to fine-grained tokens | Classic | | Targeting repos across multiple orgs | Classic (single token covers all) | +#### Push check before the agent runs + +A token can read a repository and still be refused every push. A classic PAT with no scopes, for instance, still reads public repositories. Right after the clone, the agent runs `git push --dry-run` through the same credential helper the final push uses. If GitHub refuses it, the task fails within seconds with `Token cannot push to `, naming the token type and the permission to add, instead of failing at the final push after the agent's work. The dry run sends no ref update, so the remote is not changed. Read-only workflows (`coding/pr-review-v1`) never push and skip the check. + ### AWS Credentials The agent uses Amazon Bedrock for Claude inference. You need credentials with `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` permissions. diff --git a/agent/src/repo.py b/agent/src/repo.py index 1fbb61a32..0530be032 100644 --- a/agent/src/repo.py +++ b/agent/src/repo.py @@ -142,6 +142,127 @@ def _fail_setup_command(label: str, resource: str, stderr: str, progress: Any) - ) +class PushCapabilityError(RuntimeError): + """Raised when the GitHub token can read the repository but may not push to it. + + Its message starts with ``Token cannot push to ``, the phrase the CDK + error classifier (``cdk/src/handlers/shared/error-classifier.ts``) maps to + "Insufficient GitHub token scopes", non-retryable. The orchestrator's own + preflight reports the same condition with the same phrase, so both get the same + classification.""" + + +# Ref the push preflight dry-runs to. A dry run sends no ref update, so this ref +# is never created. It must be a name the remote does not have: a dry run to an +# existing branch is checked for fast-forward, and a refusal on that ground says +# nothing about the token. +_PUSH_PREFLIGHT_REF = "refs/heads/bgagent-push-preflight" + +# What git prints when GitHub refuses the push itself. The clone has just read the +# repository, so "not found" on a push means the token may not write to it: +# GitHub sends 404 instead of 403 on a repository it does not reveal to the token. +_PUSH_DENIED_SIGNATURES: tuple[str, ...] = ( + "permission to", # remote: Permission to /.git denied to . + "write access to repository not granted", + "the requested url returned error: 401", + "the requested url returned error: 403", + "the requested url returned error: 404", + "repository not found", + "authentication failed", + "invalid username or password", +) + + +def _token_remedy(token: str, repo_url: str) -> tuple[str, str]: + """Return ``(token type, remedy)`` for a token GitHub refused a push. + + Reads only the documented type prefix of the token; the token itself never + reaches the message.""" + fine_grained = ( + f"give the token the Contents permission with Read and write access on {repo_url}" + ) + classic = "give the token the `repo` scope" + if token.startswith("github_pat_"): + return "fine-grained personal access token", fine_grained + if token.startswith("ghp_"): + return "classic personal access token", classic + if token.startswith(("ghs_", "ghu_")): + return ( + "GitHub App token", + ( + "give the app the Contents permission with Read and write access and " + f"install it on {repo_url}" + ), + ) + return ( + "GitHub token", + ( + "use a fine-grained personal access token with the Contents permission with " + f"Read and write access on {repo_url}, or a classic one with the `repo` scope" + ), + ) + + +def _preflight_push_capability(config: TaskConfig, repo_dir: str, progress: Any) -> None: + """Fail the task now if the GitHub token cannot push to the repository (#801). + + A token can authenticate and read a repository while every write is refused, + for instance a classic personal access token with no scopes, which still reads + public repositories. Nothing else in setup notices: such a token passes the + clone and the whole agent run, and the work is lost at the final push. The + orchestrator's preflight does not catch it either, because the REST API's + ``permissions.push`` describes the user's role on the repository, not what the + token may do. + + ``git push --dry-run`` asks GitHub for the push service, which GitHub refuses + to a token without write access, then stops before sending anything. It goes + through the credential helper the final push uses, so it tests that exact path + for every token type, with no scope parsing: a fine-grained token sends no + ``X-OAuth-Scopes`` header at all. The token stays in the helper, never on + disk or in the command line. + + Read-only workflows are not checked: they never push, and a token that may not + write is fit for them. + """ + if config.read_only: + return + from shell import redact_secrets + + log("SETUP", f"Checking that the GitHub token can push to {config.repo_url}...") + result = run_cmd_with_backoff( + [ + "git", + "push", + "--dry-run", + # A dry run still runs the pre-push hook, code from the cloned repository. + "--no-verify", + "origin", + f"HEAD:{_PUSH_PREFLIGHT_REF}", + ], + label="push-preflight", + cwd=repo_dir, + timeout=120, + on_retry=_clone_backoff_reporter(progress, "push-preflight"), + ) + if result.returncode == 0: + return + stderr = result.stderr or "" + if any(sig in stderr.lower() for sig in _PUSH_DENIED_SIGNATURES): + token_type, remedy = _token_remedy(config.github_token, config.repo_url) + first_line = next((ln.strip() for ln in stderr.splitlines() if ln.strip()), "") + raise PushCapabilityError( + f"Token cannot push to {config.repo_url}: the {token_type} can read the " + f"repository, but GitHub refused it write access " + f"({redact_secrets(first_line[:200])}). To fix it, {remedy}. The task " + "stopped before the agent ran, so no work was lost. Token types and the " + "permissions they need: agent/README.md, GitHub PAT — Minimal Permissions." + ) + # Transient after the retries, an egress block, or another error: the clone + # proved GitHub is reachable and the final push runs this same command, so it + # would fail the same way after the agent's work. Classify and stop. + _fail_setup_command("push-preflight", config.repo_url, stderr, progress) + + def _prepare_clone_dir(repo_dir: str, notes: list[str]) -> None: """Guarantee a clean slate at *repo_dir* before cloning. @@ -271,6 +392,9 @@ def setup_repo(config: TaskConfig, progress: Any = None) -> RepoSetup: # noqa: cwd=repo_dir, ) + # Fail in seconds, not after the agent's whole run, on a token that may not push. + _preflight_push_capability(config, repo_dir, progress) + # Branch setup head_sha_before = "" # For a DIAMOND child (2+ predecessors → base_branch set AND merge_branches diff --git a/agent/tests/test_repo.py b/agent/tests/test_repo.py index 0091fe555..52e3405ec 100644 --- a/agent/tests/test_repo.py +++ b/agent/tests/test_repo.py @@ -823,3 +823,257 @@ def test_assert_root_raises_when_git_missing(self, tmp_path): with pytest.raises(RuntimeError, match="git repository at the workspace root"): repo._assert_clone_root(str(repo_dir)) + + +class _PreflightFake(FakeRunCmd): + """FakeRunCmd that can also script the push preflight's stderr. + + The shared fake always returns an empty stderr, but the preflight classifies + a refusal by git's stderr, so it needs a fake that can return one. + """ + + def __init__(self, preflight_rc: int = 0, preflight_stderr: str = ""): + super().__init__(match_substring=True) + self._preflight_rc = preflight_rc + self._preflight_stderr = preflight_stderr + + def __call__(self, cmd, label, cwd=None, timeout=600, check=True, **kwargs): + result = super().__call__(cmd, label, cwd=cwd, timeout=timeout, check=check, **kwargs) + if label == "push-preflight": + return SimpleNamespace( + returncode=self._preflight_rc, stdout="", stderr=self._preflight_stderr + ) + return result + + +# What GitHub prints when a token that can read the repository is refused a push. +# The first is what the scope-less classic PAT of #801 produced; the second is +# the 404 GitHub sends instead of a 403 when it hides a private repository. +_DENIED_403 = ( + "remote: Permission to owner/repo.git denied to someone.\n" + "fatal: unable to access 'https://github.com/owner/repo.git/': " + "The requested URL returned error: 403" +) +_DENIED_404 = ( + "remote: Repository not found.\n" + "fatal: repository 'https://github.com/owner/repo.git/' not found" +) + + +class TestPushCapabilityPreflight: + """#801: setup_repo checks that the token can push BEFORE the agent runs. + + A token can authenticate and read a repository yet be refused every write (a + classic PAT with no scopes reads public repositories anonymously). Without + this check that token passes clone and the whole agent run, and fails only at + the final push, after the work is done and with no way to deliver it. + """ + + def _setup(self, monkeypatch, fake): + _patch_common(monkeypatch, fake) + monkeypatch.setattr(repo, "detect_default_branch", lambda url, d: "main") + + def test_writeable_task_probes_push_with_a_dry_run(self, monkeypatch): + fake = _PreflightFake() + self._setup(monkeypatch, fake) + + setup = repo.setup_repo(_config(branch_name="bgagent/task-abc/feature")) + + cmd = fake.cmd_for("push-preflight") + assert cmd is not None + # A dry run never sends a ref update, so the remote is not changed, and + # --no-verify keeps a pre-push hook from the cloned repository from running. + assert cmd[:4] == ["git", "push", "--dry-run", "--no-verify"] + assert cmd[4] == "origin" + # The probe targets a ref other than the task branch: on a branch that + # already exists on the remote, a dry run of the current HEAD can be + # refused as non-fast-forward, which says nothing about the token. + src, dst = cmd[5].split(":", 1) + assert src == "HEAD" + assert dst.startswith("refs/heads/") + assert dst != f"refs/heads/{setup.branch}" + # The credential comes from the helper at call time, never the argv. + assert "ghp_" not in " ".join(cmd) + assert "@" not in " ".join(cmd) + + def test_preflight_runs_after_auth_is_configured_and_before_branch_setup(self, monkeypatch): + fake = _PreflightFake() + self._setup(monkeypatch, fake) + + repo.setup_repo(_config()) + + labels = fake.labels() + assert labels.index("configure-git-credential-helper") < labels.index("push-preflight") + assert labels.index("push-preflight") < labels.index("create-branch") + + def test_read_only_workflow_is_not_gated(self, monkeypatch): + # coding/pr-review-v1 is read_only and resolves its PR without pushing; + # requiring write access there would refuse a token that is fit for it. + fake = _PreflightFake(preflight_rc=128, preflight_stderr=_DENIED_403) + self._setup(monkeypatch, fake) + + repo.setup_repo(_config(read_only=True)) + + assert "push-preflight" not in fake.labels() + + def test_fine_grained_token_with_contents_write_passes(self, monkeypatch): + # A fine-grained PAT has no X-OAuth-Scopes header at all; the dry run + # does not look at scopes, so it passes on the server's verdict alone. + fake = _PreflightFake(preflight_rc=0) + self._setup(monkeypatch, fake) + + setup = repo.setup_repo(_config(github_token="github_pat_" + "a" * 20)) + + assert "push-preflight" in fake.labels() + assert "create-branch" in fake.labels() + assert setup.branch + + def test_classic_token_with_repo_scope_passes(self, monkeypatch): + fake = _PreflightFake(preflight_rc=0) + self._setup(monkeypatch, fake) + + repo.setup_repo(_config(github_token="ghp_" + "a" * 36)) + + assert "create-branch" in fake.labels() + + def test_classic_token_without_scopes_fails_before_the_agent_runs(self, monkeypatch): + import pytest + + token = "ghp_" + "b" * 36 + fake = _PreflightFake(preflight_rc=128, preflight_stderr=_DENIED_403) + self._setup(monkeypatch, fake) + + with pytest.raises(repo.PushCapabilityError) as excinfo: + repo.setup_repo(_config(github_token=token)) + + message = str(excinfo.value) + # The CDK error classifier keys "Insufficient GitHub token scopes" on this + # phrase (cdk/src/handlers/shared/error-classifier.ts) — the same phrase + # the orchestrator's own preflight uses — so the task gets that title, + # its remedy and a non-retryable verdict. + assert message.startswith("Token cannot push to owner/repo") + assert "classic personal access token" in message + assert "`repo` scope" in message + assert "agent/README.md" in message + assert token not in message + # Nothing after the check ran: no branch, no mise install, no build. + labels = fake.labels() + assert "create-branch" not in labels + assert "mise-install" not in labels + assert "verify-build-pre" not in labels + + def test_hidden_repository_404_is_a_refusal_too(self, monkeypatch): + import pytest + + fake = _PreflightFake(preflight_rc=128, preflight_stderr=_DENIED_404) + self._setup(monkeypatch, fake) + + # The clone just read this repository, so "not found" on the push means + # the token may not write to it, not that the repository is missing. + with pytest.raises(repo.PushCapabilityError, match="Token cannot push to owner/repo"): + repo.setup_repo(_config(github_token="ghp_" + "b" * 36)) + + def test_fine_grained_refusal_names_the_contents_permission(self, monkeypatch): + import pytest + + fake = _PreflightFake(preflight_rc=128, preflight_stderr=_DENIED_403) + self._setup(monkeypatch, fake) + + with pytest.raises(repo.PushCapabilityError) as excinfo: + repo.setup_repo(_config(github_token="github_pat_" + "c" * 20)) + + message = str(excinfo.value) + assert "fine-grained personal access token" in message + assert "Contents" in message + assert "Read and write" in message + + def test_unknown_token_type_gets_both_remedies(self, monkeypatch): + import pytest + + fake = _PreflightFake(preflight_rc=128, preflight_stderr=_DENIED_403) + self._setup(monkeypatch, fake) + + # No token in the config: gh supplies whatever it is logged in with. + with pytest.raises(repo.PushCapabilityError) as excinfo: + repo.setup_repo(_config(github_token="")) + + message = str(excinfo.value) + assert "Contents" in message + assert "`repo` scope" in message + + def test_git_stderr_is_redacted_in_the_error(self, monkeypatch): + import pytest + + leaked = "ghp_" + "d" * 36 + fake = _PreflightFake( + preflight_rc=128, + preflight_stderr=f"remote: Permission to owner/repo.git denied to {leaked}.", + ) + self._setup(monkeypatch, fake) + + with pytest.raises(repo.PushCapabilityError) as excinfo: + repo.setup_repo(_config()) + + assert leaked not in str(excinfo.value) + + def test_transient_failure_is_not_reported_as_a_permission_problem(self, monkeypatch): + import pytest + + fake = _PreflightFake( + preflight_rc=128, + preflight_stderr=( + "fatal: unable to access 'https://github.com/owner/repo.git/': " + "The requested URL returned error: 502" + ), + ) + self._setup(monkeypatch, fake) + + # GitHub stayed unavailable through the retries: a retryable blocker, so the + # operator is not sent to change a token that is fine. + with pytest.raises(repo.DependencyUnreachableError) as excinfo: + repo.setup_repo(_config()) + + assert str(excinfo.value).startswith("BLOCKED[dependency_unreachable]:") + + def test_other_failure_stops_the_task_with_the_git_error(self, monkeypatch): + import pytest + + fake = _PreflightFake(preflight_rc=1, preflight_stderr="fatal: something unexpected") + self._setup(monkeypatch, fake) + + # Clone already proved GitHub is reachable, and the final push runs the + # same command, so a dry run that fails for another reason would fail the + # same way after the agent's work. Stop now, carrying git's message. + with pytest.raises(RuntimeError, match="push-preflight failed") as excinfo: + repo.setup_repo(_config()) + + assert not isinstance(excinfo.value, repo.PushCapabilityError) + assert "something unexpected" in str(excinfo.value) + + +class TestPushPreflightAgainstRealGit: + """The preflight's command against a real remote: it passes and changes nothing.""" + + def test_dry_run_against_a_real_remote_creates_no_ref(self, tmp_path, monkeypatch): + def git(*args, cwd): + return subprocess.run( + ["git", *args], cwd=cwd, capture_output=True, text=True, check=True + ).stdout + + remote = tmp_path / "remote.git" + work = tmp_path / "work" + git("init", "--bare", "-q", str(remote), cwd=tmp_path) + git("init", "-q", str(work), cwd=tmp_path) + git("remote", "add", "origin", str(remote), cwd=work) + monkeypatch.setenv("GIT_AUTHOR_NAME", "t") + monkeypatch.setenv("GIT_AUTHOR_EMAIL", "t@example.com") + monkeypatch.setenv("GIT_COMMITTER_NAME", "t") + monkeypatch.setenv("GIT_COMMITTER_EMAIL", "t@example.com") + git("commit", "-q", "--allow-empty", "-m", "init", cwd=work) + git("push", "-q", "origin", "HEAD:refs/heads/main", cwd=work) + refs_before = git("for-each-ref", cwd=remote) + + repo._preflight_push_capability(_config(), str(work), progress=None) + + assert git("for-each-ref", cwd=remote) == refs_before + assert "bgagent-push-preflight" not in refs_before diff --git a/cdk/test/handlers/shared/error-classifier.test.ts b/cdk/test/handlers/shared/error-classifier.test.ts index c4ea0aa78..eb53f565e 100644 --- a/cdk/test/handlers/shared/error-classifier.test.ts +++ b/cdk/test/handlers/shared/error-classifier.test.ts @@ -88,6 +88,22 @@ describe('classifyError', () => { expect(result!.title).toBe('Insufficient GitHub token scopes'); }); + test('classifies the agent push preflight refusal as insufficient token scopes (#801)', () => { + // The message agent/src/repo.py raises (PushCapabilityError) when GitHub + // refuses the dry-run push. Git's own words in it (403, "denied") must not + // pull it into another category. + const result = classifyError( + 'Token cannot push to owner/repo: the classic personal access token can read the ' + + 'repository, but GitHub refused it write access (remote: Permission to ' + + 'owner/repo.git denied to someone.). To fix it, give the token the `repo` scope. ' + + 'The task stopped before the agent ran, so no work was lost. Token types and the ' + + 'permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.', + ); + expect(result!.category).toBe(ErrorCategory.AUTH); + expect(result!.title).toBe('Insufficient GitHub token scopes'); + expect(result!.retryable).toBe(false); + }); + test('classifies bare "Token cannot interact with pull requests on" without error code', () => { const result = classifyError('Token cannot interact with pull requests on owner/repo'); expect(result!.category).toBe(ErrorCategory.AUTH); From 8ed68c33044090699f2e9bb7008a27f9a087fd7e Mon Sep 17 00:00:00 2001 From: bgagent Date: Wed, 18 Nov 2026 08:52:11 -0600 Subject: [PATCH 2/6] chore(deps): accept the picomatch ReDoS advisory until 2026-12-16 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. --- osv-scanner.toml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/osv-scanner.toml b/osv-scanner.toml index cd7490131..2b6b86dde 100644 --- a/osv-scanner.toml +++ b/osv-scanner.toml @@ -2,6 +2,11 @@ # lockfiles in this directory. Each entry expires so the scan fails again and the # finding is re-reviewed; remove an entry as soon as a fixed release is available. +[[IgnoredVulns]] +id = "GHSA-fc5q-39xc-vjpf" +ignoreUntil = 2026-12-16 +reason = "picomatch regular-expression denial of service on a crafted glob pattern (every release through 4.0.7, the latest; the advisory was updated on 2026-11-17, and on 2026-11-18 no fixed release exists). The locked copies, 2.3.2, 4.0.5 and 4.0.7, belong to build, test and lint tooling only (jest, vitest, vite, astro, knip, typescript-eslint, the ESLint stylistic plugin, the docs link validator); no runtime dependency of cdk, cli or web reaches picomatch, so no Lambda bundle, the CLI or the console ships it. They match only patterns from this repository's own configuration, never a pattern from a request. #1052 accepts the same advisory." + [[IgnoredVulns]] id = "GHSA-g3hv-75wg-m249" ignoreUntil = 2026-12-16 From 0a3e0fc97503dbaa4a358b472f7b4c71e89532c8 Mon Sep 17 00:00:00 2001 From: bgagent Date: Wed, 18 Nov 2026 09:02:09 -0600 Subject: [PATCH 3/6] fix(agent): harden the push preflight from review (#801) 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. --- agent/README.md | 12 +- agent/src/repo.py | 286 ++++++++++---- agent/tests/test_repo.py | 356 ++++++++++++------ .../handlers/shared/error-classifier.test.ts | 35 +- docs/design/SECURITY.md | 1 + docs/guides/USER_GUIDE.md | 2 +- .../src/content/docs/architecture/Security.md | 1 + .../using/Tips-for-being-a-good-citizen.md | 2 +- 8 files changed, 500 insertions(+), 195 deletions(-) diff --git a/agent/README.md b/agent/README.md index 5e41eb38d..b20883cee 100644 --- a/agent/README.md +++ b/agent/README.md @@ -56,7 +56,17 @@ Set an expiration (90 days recommended) and store it in Secrets Manager the same #### Push check before the agent runs -A token can read a repository and still be refused every push. A classic PAT with no scopes, for instance, still reads public repositories. Right after the clone, the agent runs `git push --dry-run` through the same credential helper the final push uses. If GitHub refuses it, the task fails within seconds with `Token cannot push to `, naming the token type and the permission to add, instead of failing at the final push after the agent's work. The dry run sends no ref update, so the remote is not changed. Read-only workflows (`coding/pr-review-v1`) never push and skip the check. +A token can read a repository and still be refused every push. A classic PAT with no scopes, for instance, still reads public repositories. Once the clone's remote and credential helper are set, the agent runs `git push --dry-run` through the same helper the final push uses. When GitHub refuses it, the task fails within seconds instead of at the final push after the agent's work: + +| GitHub's answer | Task error | +|-----------------|------------| +| The token may not write | `Token cannot push to `, naming the token type and the permission to add | +| The token is invalid, expired or revoked | `BLOCKED[auth_failure]`: replace the token secret | +| The repository is archived | `Cannot push to `: unarchive it or target another repository | +| The organization enforces SAML single sign-on, or an IP allow list | `Token cannot push to `, naming that cause | +| No answer (GitHub or the network down, after retries) | `BLOCKED[dependency_unreachable]`, retryable | + +The dry run sends no ref update, so the remote is not changed. It checks write access only: branch rules and push protection are evaluated on a real push. Read-only workflows (`coding/pr-review-v1`) never push and skip the check. ### AWS Credentials diff --git a/agent/src/repo.py b/agent/src/repo.py index 0530be032..d1a6dfb52 100644 --- a/agent/src/repo.py +++ b/agent/src/repo.py @@ -2,7 +2,7 @@ import os import subprocess -from typing import Any +from typing import Any, NamedTuple, NoReturn from config import AGENT_WORKSPACE from models import RepoSetup, TaskConfig @@ -62,7 +62,7 @@ class DependencyUnreachableError(RuntimeError): error classifier attaches a precise remedy.""" -def _fail_setup_command(label: str, resource: str, stderr: str, progress: Any) -> None: +def _fail_setup_command(label: str, resource: str, stderr: str, progress: Any) -> NoReturn: """Handle a failed clone/fetch after bounded retries. Three-way classification, in priority order: @@ -143,123 +143,263 @@ def _fail_setup_command(label: str, resource: str, stderr: str, progress: Any) - class PushCapabilityError(RuntimeError): - """Raised when the GitHub token can read the repository but may not push to it. + """Raised when GitHub refuses the GitHub token a push to the repository. - Its message starts with ``Token cannot push to ``, the phrase the CDK - error classifier (``cdk/src/handlers/shared/error-classifier.ts``) maps to - "Insufficient GitHub token scopes", non-retryable. The orchestrator's own - preflight reports the same condition with the same phrase, so both get the same - classification.""" + The message is the contract with the CDK error classifier + (``cdk/src/handlers/shared/error-classifier.ts``), which matches it anywhere in + the persisted error (the pipeline prefixes the type name): + - a token that lacks write access: contains ``Token cannot push to ``, + classified "Insufficient GitHub token scopes", non-retryable. The orchestrator's + preflight uses the same phrase, but its message also carries the + ``INSUFFICIENT_GITHUB_REPO_PERMISSIONS`` code, which matches first and is titled + "Insufficient GitHub permissions": same category and verdict, another title. + - a credential GitHub rejects outright: a ``BLOCKED[auth_failure]`` reason. + - an archived repository: neither, since no token change fixes it.""" -# Ref the push preflight dry-runs to. A dry run sends no ref update, so this ref -# is never created. It must be a name the remote does not have: a dry run to an -# existing branch is checked for fast-forward, and a refusal on that ground says -# nothing about the token. + +# Ref the push preflight dry-runs to. A dry run sends no ref update, so the remote +# never gets this ref. The refspec is forced: a dry run to a ref the remote already +# has is otherwise checked for fast-forward, and that refusal says nothing about the +# token. _PUSH_PREFLIGHT_REF = "refs/heads/bgagent-push-preflight" -# What git prints when GitHub refuses the push itself. The clone has just read the -# repository, so "not found" on a push means the token may not write to it: -# GitHub sends 404 instead of 403 on a repository it does not reveal to the token. -_PUSH_DENIED_SIGNATURES: tuple[str, ...] = ( +# GitHub refuses the push service to a token without write access. GitHub can answer +# 404 "Repository not found" instead of 403; the clone has just read this repository +# with the same credential, so here a 404 is a refused push, not a missing repository. +_PUSH_REFUSED_SIGNATURES: tuple[str, ...] = ( "permission to", # remote: Permission to /.git denied to . "write access to repository not granted", - "the requested url returned error: 401", "the requested url returned error: 403", "the requested url returned error: 404", "repository not found", +) + +# GitHub does not accept the credential at all: invalid, expired or revoked. A +# public repository clones without one (git sends credentials only when challenged), +# so such a token gets this far. +_CREDENTIAL_REJECTED_SIGNATURES: tuple[str, ...] = ( + "the requested url returned error: 401", "authentication failed", "invalid username or password", ) +# Refusals whose cause is the repository or the organization, not the token's +# permissions, each with its remedy. Checked before the generic refusal: GitHub sends +# them with a 403 too. +_ORG_POLICY_REFUSALS: tuple[tuple[str, str], ...] = ( + ( + "saml", + ( + "the organization enforces SAML single sign-on and the token is not authorized " + "for it. To fix it, authorize the token for the organization (GitHub > Settings " + "> Personal access tokens > Configure SSO)" + ), + ), + ( + "ip allow list", + ( + "the organization's IP allow list does not include the agent's address. To fix " + "it, add the agent's egress IP addresses to the organization's IP allow list" + ), + ), +) + + +class _TokenRemedy(NamedTuple): + kind: str # the token type, as the error names it + remedy: str + -def _token_remedy(token: str, repo_url: str) -> tuple[str, str]: - """Return ``(token type, remedy)`` for a token GitHub refused a push. +def _token_remedy(token: str, repo_url: str) -> _TokenRemedy: + """The token type and the permission to add, for a token GitHub refused a push. Reads only the documented type prefix of the token; the token itself never reaches the message.""" - fine_grained = ( - f"give the token the Contents permission with Read and write access on {repo_url}" - ) - classic = "give the token the `repo` scope" if token.startswith("github_pat_"): - return "fine-grained personal access token", fine_grained + return _TokenRemedy( + "fine-grained personal access token", + f"give the token the Contents permission with Read and write access on {repo_url}", + ) if token.startswith("ghp_"): - return "classic personal access token", classic + return _TokenRemedy("classic personal access token", "give the token the `repo` scope") if token.startswith(("ghs_", "ghu_")): - return ( + return _TokenRemedy( "GitHub App token", - ( - "give the app the Contents permission with Read and write access and " - f"install it on {repo_url}" - ), + "give the app the Contents permission with Read and write access and " + f"install it on {repo_url}", ) - return ( + return _TokenRemedy( "GitHub token", - ( - "use a fine-grained personal access token with the Contents permission with " - f"Read and write access on {repo_url}, or a classic one with the `repo` scope" - ), + "use a fine-grained personal access token with the Contents permission with " + f"Read and write access on {repo_url}, or a classic one with the `repo` scope", ) +def _matching_line(stderr: str, signatures: tuple[str, ...]) -> str: + """The first stderr line naming one of *signatures*, redacted: the line that + says why, not a ``warning:`` git may print before it.""" + from shell import redact_secrets + + lines = [ln.strip() for ln in stderr.splitlines() if ln.strip()] + line = next((ln for ln in lines if any(s in ln.lower() for s in signatures)), "") + return redact_secrets((line or (lines[0] if lines else ""))[:200]) + + +def _push_refusal(config: TaskConfig, stderr: str) -> PushCapabilityError | None: + """Classify a refused dry-run push; ``None`` when GitHub did not refuse it.""" + from progress_writer import format_blocker_reason + + low = stderr.lower() + repo_url = config.repo_url + no_loss = "The task stopped before the agent ran, so no work was lost." + if any(sig in low for sig in _CREDENTIAL_REJECTED_SIGNATURES): + line = _matching_line(stderr, _CREDENTIAL_REJECTED_SIGNATURES) + return PushCapabilityError( + format_blocker_reason( + "auth_failure", + f"GitHub rejected the token when asked to push ({line}): it is invalid, " + f"expired or revoked. Replace the GitHub token secret, then resubmit. {no_loss}", + repo_url, + ) + ) + if "archived" in low: + line = _matching_line(stderr, ("archived",)) + return PushCapabilityError( + f"Cannot push to {repo_url}: GitHub reports the repository is archived, so it " + f"is read-only ({line}). Unarchive it or target another repository. {no_loss}" + ) + for signature, cause in _ORG_POLICY_REFUSALS: + if signature in low: + line = _matching_line(stderr, (signature,)) + return PushCapabilityError( + f"Token cannot push to {repo_url}: {cause} ({line}). {no_loss}" + ) + if any(sig in low for sig in _PUSH_REFUSED_SIGNATURES): + line = _matching_line(stderr, _PUSH_REFUSED_SIGNATURES) + token_type, remedy = _token_remedy(config.github_token, repo_url) + return PushCapabilityError( + f"Token cannot push to {repo_url}: the {token_type} can read the " + f"repository, but GitHub refused it write access ({line}). To fix it, " + f"{remedy}. {no_loss} Token types and the permissions they need: " + "agent/README.md, GitHub PAT — Minimal Permissions." + ) + return None + + +def _preflight_probe_commit(repo_dir: str) -> str: + """A commit to dry-run push that every clone has, an empty repository's too. + + ``HEAD`` names no commit in a clone of an empty repository, so pushing it fails + before git contacts the remote. This commit, of the empty tree, exists in any + clone; making it writes one unreferenced object and leaves ``HEAD``, the index + and the working tree alone.""" + tree = run_cmd( + ["git", "hash-object", "-t", "tree", "/dev/null"], + label="push-preflight-tree", + cwd=repo_dir, + ).stdout.strip() + return run_cmd( + [ + "git", + "-c", + "user.name=bgagent", + "-c", + "user.email=bgagent@noreply.github.com", + "commit-tree", + tree, + "-m", + "bgagent push preflight", + ], + label="push-preflight-commit", + cwd=repo_dir, + ).stdout.strip() + + +# Seconds one dry-run attempt may take. It only lists the remote's refs. +_PUSH_PREFLIGHT_TIMEOUT_S = 120 + + def _preflight_push_capability(config: TaskConfig, repo_dir: str, progress: Any) -> None: - """Fail the task now if the GitHub token cannot push to the repository (#801). + """Fail the task now if GitHub refuses the token a push to the repository (#801). A token can authenticate and read a repository while every write is refused, for instance a classic personal access token with no scopes, which still reads public repositories. Nothing else in setup notices: such a token passes the clone and the whole agent run, and the work is lost at the final push. The - orchestrator's preflight does not catch it either, because the REST API's - ``permissions.push`` describes the user's role on the repository, not what the - token may do. + orchestrator's preflight does not catch it either: the REST API's + ``permissions.push`` and the GraphQL ``viewerPermission`` it falls back to both + describe the user's role on the repository, not what the token may do. ``git push --dry-run`` asks GitHub for the push service, which GitHub refuses - to a token without write access, then stops before sending anything. It goes - through the credential helper the final push uses, so it tests that exact path - for every token type, with no scope parsing: a fine-grained token sends no - ``X-OAuth-Scopes`` header at all. The token stays in the helper, never on - disk or in the command line. + to a token without write access, then stops before sending anything. It uses the + remote and the credential helper of the final push, so it tests that path for + every token type, with no scope parsing: GitHub returns no ``X-OAuth-Scopes`` + header for a fine-grained token. The helper reads the token from + ``GH_TOKEN``/``GITHUB_TOKEN`` at call time; it is never written to disk or passed + on the command line. The check covers write access only: branch rules and push + protection are evaluated on a real push, which a dry run never makes. Read-only workflows are not checked: they never push, and a token that may not write is fit for them. """ if config.read_only: return - from shell import redact_secrets log("SETUP", f"Checking that the GitHub token can push to {config.repo_url}...") - result = run_cmd_with_backoff( - [ - "git", - "push", - "--dry-run", - # A dry run still runs the pre-push hook, code from the cloned repository. - "--no-verify", - "origin", - f"HEAD:{_PUSH_PREFLIGHT_REF}", - ], - label="push-preflight", - cwd=repo_dir, - timeout=120, - on_retry=_clone_backoff_reporter(progress, "push-preflight"), - ) + probe = _preflight_probe_commit(repo_dir) + try: + result = run_cmd_with_backoff( + [ + "git", + "push", + "--dry-run", + # A dry run still runs the pre-push hook. Skip it: the probe tests the + # credential, and no hook a hook manager or core.hooksPath set up runs. + "--no-verify", + "origin", + f"+{probe}:{_PUSH_PREFLIGHT_REF}", + ], + label="push-preflight", + cwd=repo_dir, + timeout=_PUSH_PREFLIGHT_TIMEOUT_S, + on_retry=_clone_backoff_reporter(progress, "push-preflight"), + ) + except subprocess.TimeoutExpired: + # Unhandled, the timeout would surface as a build timeout. It is GitHub or the + # network that did not answer: report it as the retryable transient it is. + _fail_setup_command( + "push-preflight", + config.repo_url, + f"operation timed out after {_PUSH_PREFLIGHT_TIMEOUT_S}s", + progress, + ) if result.returncode == 0: return stderr = result.stderr or "" - if any(sig in stderr.lower() for sig in _PUSH_DENIED_SIGNATURES): - token_type, remedy = _token_remedy(config.github_token, config.repo_url) - first_line = next((ln.strip() for ln in stderr.splitlines() if ln.strip()), "") - raise PushCapabilityError( - f"Token cannot push to {config.repo_url}: the {token_type} can read the " - f"repository, but GitHub refused it write access " - f"({redact_secrets(first_line[:200])}). To fix it, {remedy}. The task " - "stopped before the agent ran, so no work was lost. Token types and the " - "permissions they need: agent/README.md, GitHub PAT — Minimal Permissions." - ) - # Transient after the retries, an egress block, or another error: the clone - # proved GitHub is reachable and the final push runs this same command, so it - # would fail the same way after the agent's work. Classify and stop. + refusal = _push_refusal(config, stderr) + if refusal is not None: + if progress is not None: + from hooks import _try_progress + + _try_progress( + progress, + "write_agent_blocked", + kind="auth_failure", + detail=f"GitHub refused the token a push to {config.repo_url}", + remediation_hint=( + "See the task error for the cause and the fix, then resubmit. The " + "agent never widens its own credentials." + ), + retryable=False, + resource=config.repo_url, + ) + raise refusal + # Not a refusal: a transient failure that outlasted the retries, an egress block, + # or another git error. The final push goes through the same remote, credential + # helper and transport, so going on would most likely lose the agent's work at the + # end. _fail_setup_command reports it as egress_denied, a retryable + # dependency_unreachable, or a plain RuntimeError carrying git's message. _fail_setup_command("push-preflight", config.repo_url, stderr, progress) diff --git a/agent/tests/test_repo.py b/agent/tests/test_repo.py index 52e3405ec..9d91c0614 100644 --- a/agent/tests/test_repo.py +++ b/agent/tests/test_repo.py @@ -39,6 +39,12 @@ def _patch_common(monkeypatch, fake: FakeRunCmd): # assertion on a non-existent/empty workspace path. monkeypatch.setattr(repo, "_prepare_clone_dir", lambda repo_dir, notes: None) monkeypatch.setattr(repo, "_assert_clone_root", lambda repo_dir: None) + # The push preflight makes its probe commit with real git (covered by + # TestPushPreflightAgainstRealGit); the faked workspace has no repository. + monkeypatch.setattr(repo, "_preflight_probe_commit", lambda repo_dir: _PROBE_SHA) + + +_PROBE_SHA = "c0ffee" * 6 + "c0ff" class TestSetupRepoHappyPath: @@ -826,29 +832,34 @@ def test_assert_root_raises_when_git_missing(self, tmp_path): class _PreflightFake(FakeRunCmd): - """FakeRunCmd that can also script the push preflight's stderr. + """FakeRunCmd that can also script the push preflight's stderr and timeout. The shared fake always returns an empty stderr, but the preflight classifies a refusal by git's stderr, so it needs a fake that can return one. """ - def __init__(self, preflight_rc: int = 0, preflight_stderr: str = ""): + def __init__(self, preflight_rc: int = 0, preflight_stderr: str = "", timeout=False): super().__init__(match_substring=True) self._preflight_rc = preflight_rc self._preflight_stderr = preflight_stderr + self._timeout = timeout + self.preflight_timeout = None def __call__(self, cmd, label, cwd=None, timeout=600, check=True, **kwargs): result = super().__call__(cmd, label, cwd=cwd, timeout=timeout, check=check, **kwargs) if label == "push-preflight": + self.preflight_timeout = timeout + if self._timeout: + raise subprocess.TimeoutExpired(cmd, timeout) return SimpleNamespace( returncode=self._preflight_rc, stdout="", stderr=self._preflight_stderr ) return result -# What GitHub prints when a token that can read the repository is refused a push. -# The first is what the scope-less classic PAT of #801 produced; the second is -# the 404 GitHub sends instead of a 403 when it hides a private repository. +# What GitHub prints when it refuses a push. The first is what the scope-less +# classic PAT of #801 produced; the second is the 404 GitHub can send instead of a +# 403. _DENIED_403 = ( "remote: Permission to owner/repo.git denied to someone.\n" "fatal: unable to access 'https://github.com/owner/repo.git/': " @@ -858,22 +869,46 @@ def __call__(self, cmd, label, cwd=None, timeout=600, check=True, **kwargs): "remote: Repository not found.\n" "fatal: repository 'https://github.com/owner/repo.git/' not found" ) +_REJECTED_401 = ( + "remote: Invalid username or token. Password authentication is not supported.\n" + "fatal: Authentication failed for 'https://github.com/owner/repo.git/'" +) +_ARCHIVED = ( + "remote: This repository was archived so it is read-only.\n" + "fatal: unable to access 'https://github.com/owner/repo.git/': " + "The requested URL returned error: 403" +) +_SAML = ( + "remote: The 'acme' organization has enabled or enforced SAML SSO.\n" + "remote: To access this repository, you must use a token authorized for it.\n" + "fatal: unable to access 'https://github.com/owner/repo.git/': " + "The requested URL returned error: 403" +) class TestPushCapabilityPreflight: - """#801: setup_repo checks that the token can push BEFORE the agent runs. + """#801: setup_repo checks that GitHub lets the token push BEFORE the agent runs. A token can authenticate and read a repository yet be refused every write (a - classic PAT with no scopes reads public repositories anonymously). Without - this check that token passes clone and the whole agent run, and fails only at - the final push, after the work is done and with no way to deliver it. + classic PAT with no scopes still reads public repositories). Without this check + that token passes clone and the whole agent run, and fails only at the final + push, after the work is done and with no way to deliver it. """ def _setup(self, monkeypatch, fake): _patch_common(monkeypatch, fake) monkeypatch.setattr(repo, "detect_default_branch", lambda url, d: "main") - def test_writeable_task_probes_push_with_a_dry_run(self, monkeypatch): + def _raises(self, monkeypatch, stderr, exc=None, **config): + import pytest + + fake = _PreflightFake(preflight_rc=128, preflight_stderr=stderr) + self._setup(monkeypatch, fake) + with pytest.raises(exc or repo.PushCapabilityError) as excinfo: + repo.setup_repo(_config(**config)) + return fake, str(excinfo.value) + + def test_writeable_task_probes_push_with_a_forced_dry_run(self, monkeypatch): fake = _PreflightFake() self._setup(monkeypatch, fake) @@ -882,19 +917,19 @@ def test_writeable_task_probes_push_with_a_dry_run(self, monkeypatch): cmd = fake.cmd_for("push-preflight") assert cmd is not None # A dry run never sends a ref update, so the remote is not changed, and - # --no-verify keeps a pre-push hook from the cloned repository from running. + # --no-verify keeps a pre-push hook from running. assert cmd[:4] == ["git", "push", "--dry-run", "--no-verify"] assert cmd[4] == "origin" - # The probe targets a ref other than the task branch: on a branch that - # already exists on the remote, a dry run of the current HEAD can be - # refused as non-fast-forward, which says nothing about the token. + # Forced, from the probe commit (HEAD names no commit in an empty clone), + # to a ref other than the task branch. src, dst = cmd[5].split(":", 1) - assert src == "HEAD" + assert src == f"+{_PROBE_SHA}" assert dst.startswith("refs/heads/") assert dst != f"refs/heads/{setup.branch}" # The credential comes from the helper at call time, never the argv. assert "ghp_" not in " ".join(cmd) assert "@" not in " ".join(cmd) + assert fake.preflight_timeout == 120 def test_preflight_runs_after_auth_is_configured_and_before_branch_setup(self, monkeypatch): fake = _PreflightFake() @@ -907,8 +942,8 @@ def test_preflight_runs_after_auth_is_configured_and_before_branch_setup(self, m assert labels.index("push-preflight") < labels.index("create-branch") def test_read_only_workflow_is_not_gated(self, monkeypatch): - # coding/pr-review-v1 is read_only and resolves its PR without pushing; - # requiring write access there would refuse a token that is fit for it. + # coding/pr-review-v1 is read_only: it reviews and comments on the PR and + # never pushes, so a token without write access is fit for it. fake = _PreflightFake(preflight_rc=128, preflight_stderr=_DENIED_403) self._setup(monkeypatch, fake) @@ -916,17 +951,24 @@ def test_read_only_workflow_is_not_gated(self, monkeypatch): assert "push-preflight" not in fake.labels() - def test_fine_grained_token_with_contents_write_passes(self, monkeypatch): - # A fine-grained PAT has no X-OAuth-Scopes header at all; the dry run - # does not look at scopes, so it passes on the server's verdict alone. + def test_read_only_matches_the_shipped_workflows_that_never_push(self): + # The skip keys on read_only; the issue's rule is "never pushes". Tie the + # two together for the workflows the image ships. + from workflow import load_workflow + + assert load_workflow("coding/pr-review-v1").read_only is True + for pushing in ("coding/new-task-v1", "coding/pr-iteration-v1", "coding/restack-v1"): + assert load_workflow(pushing).read_only is False, pushing + + def test_fine_grained_token_passes_on_the_servers_verdict(self, monkeypatch): + # A fine-grained PAT gets no X-OAuth-Scopes header back from GitHub; the dry + # run reads no scopes, so it passes on the server's verdict alone. fake = _PreflightFake(preflight_rc=0) self._setup(monkeypatch, fake) - setup = repo.setup_repo(_config(github_token="github_pat_" + "a" * 20)) + repo.setup_repo(_config(github_token="github_pat_" + "a" * 20)) - assert "push-preflight" in fake.labels() assert "create-branch" in fake.labels() - assert setup.branch def test_classic_token_with_repo_scope_passes(self, monkeypatch): fake = _PreflightFake(preflight_rc=0) @@ -937,143 +979,237 @@ def test_classic_token_with_repo_scope_passes(self, monkeypatch): assert "create-branch" in fake.labels() def test_classic_token_without_scopes_fails_before_the_agent_runs(self, monkeypatch): - import pytest - token = "ghp_" + "b" * 36 - fake = _PreflightFake(preflight_rc=128, preflight_stderr=_DENIED_403) - self._setup(monkeypatch, fake) - - with pytest.raises(repo.PushCapabilityError) as excinfo: - repo.setup_repo(_config(github_token=token)) + fake, message = self._raises(monkeypatch, _DENIED_403, github_token=token) - message = str(excinfo.value) - # The CDK error classifier keys "Insufficient GitHub token scopes" on this - # phrase (cdk/src/handlers/shared/error-classifier.ts) — the same phrase - # the orchestrator's own preflight uses — so the task gets that title, - # its remedy and a non-retryable verdict. + # The CDK error classifier maps this phrase to "Insufficient GitHub token + # scopes" (cdk/src/handlers/shared/error-classifier.ts). assert message.startswith("Token cannot push to owner/repo") assert "classic personal access token" in message assert "`repo` scope" in message + assert "Permission to owner/repo.git denied" in message assert "agent/README.md" in message assert token not in message - # Nothing after the check ran: no branch, no mise install, no build. - labels = fake.labels() - assert "create-branch" not in labels - assert "mise-install" not in labels - assert "verify-build-pre" not in labels + # No later setup step ran: no branch, no mise install, no build. + assert fake.labels()[-1] == "push-preflight" - def test_hidden_repository_404_is_a_refusal_too(self, monkeypatch): - import pytest - - fake = _PreflightFake(preflight_rc=128, preflight_stderr=_DENIED_404) - self._setup(monkeypatch, fake) + def test_404_after_a_successful_clone_is_a_refusal(self, monkeypatch): + # The clone just read this repository with the same credential, so "not + # found" on the push means the token may not write to it. + _, message = self._raises(monkeypatch, _DENIED_404, github_token="ghp_" + "b" * 36) - # The clone just read this repository, so "not found" on the push means - # the token may not write to it, not that the repository is missing. - with pytest.raises(repo.PushCapabilityError, match="Token cannot push to owner/repo"): - repo.setup_repo(_config(github_token="ghp_" + "b" * 36)) + assert message.startswith("Token cannot push to owner/repo") def test_fine_grained_refusal_names_the_contents_permission(self, monkeypatch): - import pytest - - fake = _PreflightFake(preflight_rc=128, preflight_stderr=_DENIED_403) - self._setup(monkeypatch, fake) - - with pytest.raises(repo.PushCapabilityError) as excinfo: - repo.setup_repo(_config(github_token="github_pat_" + "c" * 20)) + _, message = self._raises(monkeypatch, _DENIED_403, github_token="github_pat_" + "c" * 20) - message = str(excinfo.value) assert "fine-grained personal access token" in message - assert "Contents" in message - assert "Read and write" in message + assert "Contents permission with Read and write access" in message def test_unknown_token_type_gets_both_remedies(self, monkeypatch): - import pytest - - fake = _PreflightFake(preflight_rc=128, preflight_stderr=_DENIED_403) - self._setup(monkeypatch, fake) - # No token in the config: gh supplies whatever it is logged in with. - with pytest.raises(repo.PushCapabilityError) as excinfo: - repo.setup_repo(_config(github_token="")) + _, message = self._raises(monkeypatch, _DENIED_403, github_token="") - message = str(excinfo.value) - assert "Contents" in message + assert "Contents permission" in message assert "`repo` scope" in message - def test_git_stderr_is_redacted_in_the_error(self, monkeypatch): - import pytest + def test_github_app_token_remedy(self): + remedy = repo._token_remedy("ghs_" + "e" * 36, "owner/repo") + + assert remedy.kind == "GitHub App token" + assert "install it on owner/repo" in remedy.remedy + + def test_rejected_credential_is_an_auth_failure_not_a_scope_problem(self, monkeypatch): + # A revoked or expired token: a public repository cloned without it, but + # GitHub rejects it at the push. Adding scopes would not help. + _, message = self._raises(monkeypatch, _REJECTED_401, github_token="ghp_" + "f" * 36) + + assert message.startswith("BLOCKED[auth_failure]:") + assert "(resource: owner/repo)" in message + assert "invalid, expired or revoked" in message + assert "Token cannot push" not in message + assert "can read the repository" not in message + + def test_archived_repository_is_not_blamed_on_the_token(self, monkeypatch): + _, message = self._raises(monkeypatch, _ARCHIVED, github_token="ghp_" + "b" * 36) + + assert message.startswith("Cannot push to owner/repo") + assert "archived" in message + # Not the phrase the classifier reads as a token-scope problem. + assert "Token cannot push" not in message + assert "`repo` scope" not in message + + def test_saml_enforcement_names_sso_authorization(self, monkeypatch): + _, message = self._raises(monkeypatch, _SAML, github_token="ghp_" + "b" * 36) + + assert message.startswith("Token cannot push to owner/repo") + assert "SAML single sign-on" in message + assert "`repo` scope" not in message + + def test_error_quotes_the_line_that_says_why(self, monkeypatch): + stderr = "warning: redirecting to https://github.com/owner/repo.git/\n" + _DENIED_403 + _, message = self._raises(monkeypatch, stderr) + + assert "Permission to owner/repo.git denied" in message + assert "redirecting" not in message + def test_git_stderr_is_redacted_in_the_error(self, monkeypatch): leaked = "ghp_" + "d" * 36 - fake = _PreflightFake( - preflight_rc=128, - preflight_stderr=f"remote: Permission to owner/repo.git denied to {leaked}.", + _, message = self._raises( + monkeypatch, f"remote: Permission to owner/repo.git denied to {leaked}." ) + + assert leaked not in message + + def test_refusal_is_reported_on_the_live_stream(self, monkeypatch): + import pytest + + fake = _PreflightFake(preflight_rc=128, preflight_stderr=_DENIED_403) self._setup(monkeypatch, fake) + progress = _RecordingProgress() - with pytest.raises(repo.PushCapabilityError) as excinfo: - repo.setup_repo(_config()) + with pytest.raises(repo.PushCapabilityError): + repo.setup_repo(_config(), progress=progress) - assert leaked not in str(excinfo.value) + blocked = [kw for name, kw in progress.calls if name == "write_agent_blocked"] + assert len(blocked) == 1 + assert blocked[0]["kind"] == "auth_failure" + assert blocked[0]["retryable"] is False + assert blocked[0]["resource"] == "owner/repo" def test_transient_failure_is_not_reported_as_a_permission_problem(self, monkeypatch): + # Simulates GitHub staying unavailable after the retries: a retryable + # blocker, so the operator is not sent to change a token that is fine. + _, message = self._raises( + monkeypatch, + "fatal: unable to access 'https://github.com/owner/repo.git/': " + "The requested URL returned error: 502", + exc=repo.DependencyUnreachableError, + ) + + assert message.startswith("BLOCKED[dependency_unreachable]:") + + def test_timeout_is_a_retryable_dependency_failure_not_a_build_timeout(self, monkeypatch): import pytest - fake = _PreflightFake( - preflight_rc=128, - preflight_stderr=( - "fatal: unable to access 'https://github.com/owner/repo.git/': " - "The requested URL returned error: 502" - ), - ) + fake = _PreflightFake(timeout=True) self._setup(monkeypatch, fake) - # GitHub stayed unavailable through the retries: a retryable blocker, so the - # operator is not sent to change a token that is fine. + # Unhandled, TimeoutExpired would be classified "Build/tests didn't finish". with pytest.raises(repo.DependencyUnreachableError) as excinfo: repo.setup_repo(_config()) assert str(excinfo.value).startswith("BLOCKED[dependency_unreachable]:") + def test_unresolvable_host_is_an_egress_block(self, monkeypatch): + _, message = self._raises( + monkeypatch, + "fatal: unable to access 'https://github.com/owner/repo.git/': " + "Could not resolve host: github.com", + exc=repo.DependencyUnreachableError, + ) + + assert message.startswith("BLOCKED[egress_denied]:") + assert "(resource: github.com)" in message + def test_other_failure_stops_the_task_with_the_git_error(self, monkeypatch): - import pytest + # The final push goes through the same remote and credential helper, so a + # dry run that fails for another reason would most likely fail it too. + _, message = self._raises(monkeypatch, "fatal: something unexpected", exc=RuntimeError) - fake = _PreflightFake(preflight_rc=1, preflight_stderr="fatal: something unexpected") - self._setup(monkeypatch, fake) + assert "push-preflight failed" in message + assert "something unexpected" in message - # Clone already proved GitHub is reachable, and the final push runs the - # same command, so a dry run that fails for another reason would fail the - # same way after the agent's work. Stop now, carrying git's message. - with pytest.raises(RuntimeError, match="push-preflight failed") as excinfo: - repo.setup_repo(_config()) + def test_pr_iteration_is_checked_before_its_branch_is_fetched(self, monkeypatch): + # pr-iteration and restack push their PR branch too (push_resolve). + fake, _ = self._raises( + monkeypatch, + _DENIED_403, + is_pr_workflow=True, + branch_name="feature/x", + base_branch="develop", + ) + + assert "fetch-pr-branch" not in fake.labels() + assert "checkout-pr-branch" not in fake.labels() + + def test_stacked_child_is_checked_before_its_base_is_fetched(self, monkeypatch): + fake, _ = self._raises( + monkeypatch, _DENIED_403, branch_name="bgagent/t/child", base_branch="pred" + ) - assert not isinstance(excinfo.value, repo.PushCapabilityError) - assert "something unexpected" in str(excinfo.value) + assert "fetch-base-branch" not in fake.labels() class TestPushPreflightAgainstRealGit: - """The preflight's command against a real remote: it passes and changes nothing.""" + """The preflight's commands against a real git remote (a local bare repository): + it passes, changes nothing, and does not depend on HEAD or on hooks.""" - def test_dry_run_against_a_real_remote_creates_no_ref(self, tmp_path, monkeypatch): - def git(*args, cwd): - return subprocess.run( - ["git", *args], cwd=cwd, capture_output=True, text=True, check=True - ).stdout + @staticmethod + def _git(*args, cwd): + return subprocess.run( + ["git", *args], cwd=cwd, capture_output=True, text=True, check=True + ).stdout - remote = tmp_path / "remote.git" - work = tmp_path / "work" - git("init", "--bare", "-q", str(remote), cwd=tmp_path) - git("init", "-q", str(work), cwd=tmp_path) - git("remote", "add", "origin", str(remote), cwd=work) + def _remote_and_clone(self, tmp_path, monkeypatch, *, empty=False): monkeypatch.setenv("GIT_AUTHOR_NAME", "t") monkeypatch.setenv("GIT_AUTHOR_EMAIL", "t@example.com") monkeypatch.setenv("GIT_COMMITTER_NAME", "t") monkeypatch.setenv("GIT_COMMITTER_EMAIL", "t@example.com") - git("commit", "-q", "--allow-empty", "-m", "init", cwd=work) - git("push", "-q", "origin", "HEAD:refs/heads/main", cwd=work) - refs_before = git("for-each-ref", cwd=remote) + remote = tmp_path / "remote.git" + self._git("init", "--bare", "-q", "-b", "main", str(remote), cwd=tmp_path) + if not empty: + seed = tmp_path / "seed" + self._git("init", "-q", str(seed), cwd=tmp_path) + self._git("commit", "-q", "--allow-empty", "-m", "init", cwd=seed) + self._git("push", "-q", str(remote), "HEAD:refs/heads/main", cwd=tmp_path / "seed") + work = tmp_path / "work" + self._git("clone", "-q", str(remote), str(work), cwd=tmp_path) + return remote, work + + def test_dry_run_creates_no_ref_and_leaves_the_clone_alone(self, tmp_path, monkeypatch): + remote, work = self._remote_and_clone(tmp_path, monkeypatch) + refs_before = self._git("for-each-ref", cwd=remote) + head_before = self._git("rev-parse", "HEAD", cwd=work) + config_before = (work / ".git" / "config").read_text() repo._preflight_push_capability(_config(), str(work), progress=None) - assert git("for-each-ref", cwd=remote) == refs_before + assert self._git("for-each-ref", cwd=remote) == refs_before assert "bgagent-push-preflight" not in refs_before + assert self._git("rev-parse", "HEAD", cwd=work) == head_before + assert self._git("status", "--porcelain", cwd=work) == "" + assert (work / ".git" / "config").read_text() == config_before + + def test_empty_repository_passes(self, tmp_path, monkeypatch): + # HEAD names no commit in a clone of an empty repository; the probe commit + # does not need one. + remote, work = self._remote_and_clone(tmp_path, monkeypatch, empty=True) + + repo._preflight_push_capability(_config(), str(work), progress=None) + + assert self._git("for-each-ref", cwd=remote) == "" + + def test_existing_ref_with_the_probe_name_does_not_block(self, tmp_path, monkeypatch): + remote, work = self._remote_and_clone(tmp_path, monkeypatch) + # Someone pushed an unrelated branch with the probe's name. + other = tmp_path / "other" + self._git("init", "-q", str(other), cwd=tmp_path) + self._git("commit", "-q", "--allow-empty", "-m", "unrelated", cwd=other) + self._git("push", "-q", str(remote), "HEAD:refs/heads/bgagent-push-preflight", cwd=other) + refs_before = self._git("for-each-ref", cwd=remote) + + repo._preflight_push_capability(_config(), str(work), progress=None) + + assert self._git("for-each-ref", cwd=remote) == refs_before + + def test_pre_push_hook_does_not_run(self, tmp_path, monkeypatch): + _, work = self._remote_and_clone(tmp_path, monkeypatch) + marker = tmp_path / "hook-ran" + hook = work / ".git" / "hooks" / "pre-push" + hook.write_text(f"#!/bin/sh\ntouch {marker}\nexit 1\n") + hook.chmod(0o755) + + repo._preflight_push_capability(_config(), str(work), progress=None) + + assert not marker.exists() diff --git a/cdk/test/handlers/shared/error-classifier.test.ts b/cdk/test/handlers/shared/error-classifier.test.ts index eb53f565e..2b46c65c1 100644 --- a/cdk/test/handlers/shared/error-classifier.test.ts +++ b/cdk/test/handlers/shared/error-classifier.test.ts @@ -88,22 +88,39 @@ describe('classifyError', () => { expect(result!.title).toBe('Insufficient GitHub token scopes'); }); - test('classifies the agent push preflight refusal as insufficient token scopes (#801)', () => { - // The message agent/src/repo.py raises (PushCapabilityError) when GitHub - // refuses the dry-run push. Git's own words in it (403, "denied") must not - // pull it into another category. + // The errors agent/src/repo.py raises (PushCapabilityError) when GitHub refuses + // the dry-run push, in the form the pipeline persists them: prefixed with the + // exception's type name. + test.each([ + ['remote denial', 'remote: Permission to owner/repo.git denied to someone.'], + ['HTTP 403', 'fatal: unable to access \'https://github.com/owner/repo.git/\': The requested URL returned error: 403'], + ])('classifies the agent push preflight refusal quoting a %s line as insufficient token scopes (#801)', (_label, gitLine) => { + // The git line embedded in it ("denied", "403") must not move it to another title. const result = classifyError( - 'Token cannot push to owner/repo: the classic personal access token can read the ' - + 'repository, but GitHub refused it write access (remote: Permission to ' - + 'owner/repo.git denied to someone.). To fix it, give the token the `repo` scope. ' - + 'The task stopped before the agent ran, so no work was lost. Token types and the ' - + 'permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.', + 'PushCapabilityError: Token cannot push to owner/repo: the classic personal access ' + + `token can read the repository, but GitHub refused it write access (${gitLine}). ` + + 'To fix it, give the token the `repo` scope. The task stopped before the agent ran, ' + + 'so no work was lost. Token types and the permissions they need: agent/README.md, ' + + 'GitHub PAT — Minimal Permissions.', ); expect(result!.category).toBe(ErrorCategory.AUTH); expect(result!.title).toBe('Insufficient GitHub token scopes'); expect(result!.retryable).toBe(false); }); + test('classifies the agent push preflight credential rejection as an auth blocker (#801)', () => { + const result = classifyError( + 'PushCapabilityError: BLOCKED[auth_failure]: GitHub rejected the token when asked to ' + + 'push (fatal: Authentication failed for \'https://github.com/owner/repo.git/\'): it is ' + + 'invalid, expired or revoked. Replace the GitHub token secret, then resubmit. The task ' + + 'stopped before the agent ran, so no work was lost. (resource: owner/repo)', + ); + expect(result!.category).toBe(ErrorCategory.BLOCKED); + expect(result!.title).toBe('Blocked: authentication rejected'); + expect(result!.description).toContain('owner/repo'); + expect(result!.retryable).toBe(false); + }); + test('classifies bare "Token cannot interact with pull requests on" without error code', () => { const result = classifyError('Token cannot interact with pull requests on owner/repo'); expect(result!.category).toBe(ErrorCategory.AUTH); diff --git a/docs/design/SECURITY.md b/docs/design/SECURITY.md index 55e7a1959..d30e5d335 100644 --- a/docs/design/SECURITY.md +++ b/docs/design/SECURITY.md @@ -154,6 +154,7 @@ flowchart LR | Admission | Concurrency limit | `orchestrator.ts` | `admission_queued` event | | Pre-flight | GitHub access, PAT permissions, PR access | `preflight.ts` | `preflight_failed` event | | Hydration | Guardrail prompt screening | `context-hydration.ts` | `guardrail_blocked` event | +| Repo setup | GitHub token may push (dry-run push, skipped for read-only workflows) | `agent/src/repo.py` | `agent_blocked` event, task `FAILED` before the agent runs | | Hydration | Budget/quota resolution | `orchestrator.ts` | Persisted on task record | | Execution | Tool-call policy (Cedar) | `agent/src/hooks.py`, `agent/src/policy.py` | `POLICY_DECISION` telemetry | | Execution | Output secret screening | `agent/src/output_scanner.py` | `OUTPUT_SCREENING` telemetry | diff --git a/docs/guides/USER_GUIDE.md b/docs/guides/USER_GUIDE.md index 1e77c70a2..7f4dbf08c 100644 --- a/docs/guides/USER_GUIDE.md +++ b/docs/guides/USER_GUIDE.md @@ -1192,7 +1192,7 @@ The agent is only as good as the context it receives. A well-prepared repository - **Onboard first** - Repositories must be registered via a Blueprint construct before tasks can target them. If you get a `REPO_NOT_ONBOARDED` error, contact your platform administrator. - **Add a CLAUDE.md** - This is the single most impactful thing you can do. The agent loads project configuration from `CLAUDE.md`, `.claude/rules/*.md`, `.claude/settings.json`, and `.mcp.json` in your repository. Use these to document build commands, coding conventions, architecture decisions, and constraints. A good `CLAUDE.md` prevents the agent from guessing and reduces wasted turns. See the [Prompt guide](./PROMPT_GUIDE.md#repo-level-instructions) for examples. -- **Keep your PAT aligned** - If tasks fail with `preflight_failed`, the GitHub PAT likely lacks the permissions the task type needs. Check the event's `reason` field and update the secret in Secrets Manager. See [Repository preparation](./DEVELOPER_GUIDE.md#repository-preparation) for the full permissions table. +- **Keep your PAT aligned** - If tasks fail with `preflight_failed`, the GitHub PAT likely lacks the permissions the task type needs. Check the event's `reason` field and update the secret in Secrets Manager. A task that fails with `Token cannot push to ` passed that check, but GitHub refused the token a push when the agent tested it right after cloning, before any work was done: the error names the token type and the permission to add. See [Repository preparation](./DEVELOPER_GUIDE.md#repository-preparation) for the full permissions table. ### Write effective task descriptions diff --git a/docs/src/content/docs/architecture/Security.md b/docs/src/content/docs/architecture/Security.md index 906f08d71..142565c1c 100644 --- a/docs/src/content/docs/architecture/Security.md +++ b/docs/src/content/docs/architecture/Security.md @@ -156,6 +156,7 @@ flowchart LR | Admission | Concurrency limit | `orchestrator.ts` | `admission_queued` event | | Pre-flight | GitHub access, PAT permissions, PR access | `preflight.ts` | `preflight_failed` event | | Hydration | Guardrail prompt screening | `context-hydration.ts` | `guardrail_blocked` event | +| Repo setup | GitHub token may push (dry-run push, skipped for read-only workflows) | `agent/src/repo.py` | `agent_blocked` event, task `FAILED` before the agent runs | | Hydration | Budget/quota resolution | `orchestrator.ts` | Persisted on task record | | Execution | Tool-call policy (Cedar) | `agent/src/hooks.py`, `agent/src/policy.py` | `POLICY_DECISION` telemetry | | Execution | Output secret screening | `agent/src/output_scanner.py` | `OUTPUT_SCREENING` telemetry | diff --git a/docs/src/content/docs/using/Tips-for-being-a-good-citizen.md b/docs/src/content/docs/using/Tips-for-being-a-good-citizen.md index 475241563..bbdd2bf45 100644 --- a/docs/src/content/docs/using/Tips-for-being-a-good-citizen.md +++ b/docs/src/content/docs/using/Tips-for-being-a-good-citizen.md @@ -10,7 +10,7 @@ The agent is only as good as the context it receives. A well-prepared repository - **Onboard first** - Repositories must be registered via a Blueprint construct before tasks can target them. If you get a `REPO_NOT_ONBOARDED` error, contact your platform administrator. - **Add a CLAUDE.md** - This is the single most impactful thing you can do. The agent loads project configuration from `CLAUDE.md`, `.claude/rules/*.md`, `.claude/settings.json`, and `.mcp.json` in your repository. Use these to document build commands, coding conventions, architecture decisions, and constraints. A good `CLAUDE.md` prevents the agent from guessing and reduces wasted turns. See the [Prompt guide](/sample-autonomous-cloud-coding-agents/customizing/prompt-engineering#repo-level-instructions) for examples. -- **Keep your PAT aligned** - If tasks fail with `preflight_failed`, the GitHub PAT likely lacks the permissions the task type needs. Check the event's `reason` field and update the secret in Secrets Manager. See [Repository preparation](/sample-autonomous-cloud-coding-agents/developer-guide/repository-preparation) for the full permissions table. +- **Keep your PAT aligned** - If tasks fail with `preflight_failed`, the GitHub PAT likely lacks the permissions the task type needs. Check the event's `reason` field and update the secret in Secrets Manager. A task that fails with `Token cannot push to ` passed that check, but GitHub refused the token a push when the agent tested it right after cloning, before any work was done: the error names the token type and the permission to add. See [Repository preparation](/sample-autonomous-cloud-coding-agents/developer-guide/repository-preparation) for the full permissions table. ### Write effective task descriptions From 49192457cf286550ddcb0b393921ebe2cc11a760 Mon Sep 17 00:00:00 2001 From: bgagent Date: Wed, 18 Nov 2026 09:23:14 -0600 Subject: [PATCH 4/6] fix(agent): classify push preflight refusals by GitHub's message, not 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 "; "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). --- agent/README.md | 8 +- agent/src/repo.py | 243 ++++++++++------ agent/src/shell.py | 1 + agent/tests/test_repo.py | 275 ++++++++++++++---- agent/tests/test_shell.py | 2 + cdk/src/handlers/shared/error-classifier.ts | 25 ++ .../handlers/shared/error-classifier.test.ts | 66 +++-- docs/design/SECURITY.md | 2 +- docs/guides/USER_GUIDE.md | 2 +- .../src/content/docs/architecture/Security.md | 2 +- .../using/Tips-for-being-a-good-citizen.md | 2 +- osv-scanner.toml | 2 +- 12 files changed, 451 insertions(+), 179 deletions(-) diff --git a/agent/README.md b/agent/README.md index b20883cee..bc73bf851 100644 --- a/agent/README.md +++ b/agent/README.md @@ -61,10 +61,10 @@ A token can read a repository and still be refused every push. A classic PAT wit | GitHub's answer | Task error | |-----------------|------------| | The token may not write | `Token cannot push to `, naming the token type and the permission to add | -| The token is invalid, expired or revoked | `BLOCKED[auth_failure]`: replace the token secret | -| The repository is archived | `Cannot push to `: unarchive it or target another repository | -| The organization enforces SAML single sign-on, or an IP allow list | `Token cannot push to `, naming that cause | -| No answer (GitHub or the network down, after retries) | `BLOCKED[dependency_unreachable]`, retryable | +| No credential accepted (the token was revoked or expired after the clone; an invalid one already fails at `preflight_failed`) | `BLOCKED[auth_failure]`: replace the token secret | +| The repository is archived | `Repository is archived on GitHub`: unarchive it or target another repository | +| The organization enforces SAML single sign-on, or an IP allow list | `GitHub organization policy blocks pushes to `, naming the policy and its fix | +| No answer: GitHub or the network down after retries, or no reply within 120 s | `BLOCKED[dependency_unreachable]`, retryable | The dry run sends no ref update, so the remote is not changed. It checks write access only: branch rules and push protection are evaluated on a real push. Read-only workflows (`coding/pr-review-v1`) never push and skip the check. diff --git a/agent/src/repo.py b/agent/src/repo.py index d1a6dfb52..0a50bc9f0 100644 --- a/agent/src/repo.py +++ b/agent/src/repo.py @@ -1,6 +1,7 @@ """Repository setup: clone, branch, mise install, initial build.""" import os +import re import subprocess from typing import Any, NamedTuple, NoReturn @@ -63,7 +64,7 @@ class DependencyUnreachableError(RuntimeError): def _fail_setup_command(label: str, resource: str, stderr: str, progress: Any) -> NoReturn: - """Handle a failed clone/fetch after bounded retries. + """Handle a failed clone, fetch or push preflight after bounded retries. Three-way classification, in priority order: @@ -76,10 +77,11 @@ def _fail_setup_command(label: str, resource: str, stderr: str, progress: Any) - reaches for the identical stderr (they must not disagree). 2. **Transient** — a DNS/registry blip that survived the retries with no nameable host: report a retryable ``dependency_unreachable`` blocker. - 3. **Permanent** — repo not found, auth denied: re-raise a plain - ``RuntimeError`` carrying the redacted git stderr, preserving the original - ``check=True`` behavior so the classifier routes it to the right (auth / - not-found) remedy rather than mislabeling it retryable. + 3. **Permanent** — repo not found, auth denied, any other git error: re-raise + a plain ``RuntimeError`` carrying the redacted git stderr, preserving the + original ``check=True`` behavior so it is never mislabeled retryable. The + classifier names an auth or not-found remedy when the stderr matches one of + its patterns, and "Unexpected error" otherwise. Never widens creds/egress — it only reports.""" # (1) Egress denial takes priority over the transient set: several signatures @@ -143,19 +145,27 @@ def _fail_setup_command(label: str, resource: str, stderr: str, progress: Any) - class PushCapabilityError(RuntimeError): - """Raised when GitHub refuses the GitHub token a push to the repository. + """Raised when GitHub refuses the push the preflight tries. The message is the contract with the CDK error classifier (``cdk/src/handlers/shared/error-classifier.ts``), which matches it anywhere in - the persisted error (the pipeline prefixes the type name): + the persisted error (the pipeline prefixes the type name). Per ``cause``: - - a token that lacks write access: contains ``Token cannot push to ``, - classified "Insufficient GitHub token scopes", non-retryable. The orchestrator's - preflight uses the same phrase, but its message also carries the - ``INSUFFICIENT_GITHUB_REPO_PERMISSIONS`` code, which matches first and is titled - "Insufficient GitHub permissions": same category and verdict, another title. - - a credential GitHub rejects outright: a ``BLOCKED[auth_failure]`` reason. - - an archived repository: neither, since no token change fixes it.""" + - ``no_write``: contains ``Token cannot push to ``, classified + "Insufficient GitHub token scopes". The orchestrator's preflight uses the same + phrase, but its message also carries the ``INSUFFICIENT_GITHUB_REPO_PERMISSIONS`` + code, which matches first and is titled "Insufficient GitHub permissions": same + category and verdict, another title. + - ``credential_rejected``: a ``BLOCKED[auth_failure]`` reason. + - ``org_policy``: contains ``GitHub organization policy blocks pushes to``. + - ``archived``: contains ``is archived on GitHub, so it is read-only``. + + ``cause`` also picks the live ``agent_blocked`` event, so it cannot disagree + with the message.""" + + def __init__(self, message: str, *, cause: str) -> None: + super().__init__(message) + self.cause = cause # Ref the push preflight dry-runs to. A dry run sends no ref update, so the remote @@ -164,9 +174,9 @@ class PushCapabilityError(RuntimeError): # token. _PUSH_PREFLIGHT_REF = "refs/heads/bgagent-push-preflight" -# GitHub refuses the push service to a token without write access. GitHub can answer -# 404 "Repository not found" instead of 403; the clone has just read this repository -# with the same credential, so here a 404 is a refused push, not a missing repository. +# GitHub refuses the push service to a token without write access, with 403 or with +# 404 "Repository not found". The clone has just fetched this repository, so it +# exists: here a 404 is a refused push, not a missing repository. _PUSH_REFUSED_SIGNATURES: tuple[str, ...] = ( "permission to", # remote: Permission to /.git denied to . "write access to repository not granted", @@ -175,39 +185,51 @@ class PushCapabilityError(RuntimeError): "repository not found", ) -# GitHub does not accept the credential at all: invalid, expired or revoked. A -# public repository clones without one (git sends credentials only when challenged), -# so such a token gets this far. +# GitHub did not accept a credential for the push, or none was sent. An invalid +# token fails earlier (the orchestrator's preflight and ``gh repo clone`` both send +# it), so here it was revoked or expired after the clone, or the helper supplied none. _CREDENTIAL_REJECTED_SIGNATURES: tuple[str, ...] = ( "the requested url returned error: 401", "authentication failed", "invalid username or password", + "invalid username or token", + "could not read username", + "terminal prompts disabled", ) -# Refusals whose cause is the repository or the organization, not the token's -# permissions, each with its remedy. Checked before the generic refusal: GitHub sends -# them with a 403 too. +# Refusals caused by an organization policy, not by the token's permissions: GitHub +# sends them with a 403 too. Whole phrases from GitHub's ``remote:`` lines, which a +# user, organization or repository name (one word) cannot contain. _ORG_POLICY_REFUSALS: tuple[tuple[str, str], ...] = ( ( - "saml", + "saml sso", ( - "the organization enforces SAML single sign-on and the token is not authorized " - "for it. To fix it, authorize the token for the organization (GitHub > Settings " - "> Personal access tokens > Configure SSO)" + "it enforces SAML single sign-on and the token is not authorized for it. To fix " + "it, authorize the classic token for the organization (GitHub > Settings > " + "Developer settings > Personal access tokens > Tokens (classic) > Configure SSO)" ), ), ( "ip allow list", ( - "the organization's IP allow list does not include the agent's address. To fix " - "it, add the agent's egress IP addresses to the organization's IP allow list" + "its IP allow list does not include the agent's address. To fix it, add the " + "agent's egress IP addresses to the organization's IP allow list" ), ), ) +_ARCHIVED_SIGNATURE = "this repository was archived so it is read-only" + +# The live event for each refusal cause: (blocker kind, detail). +_REFUSAL_EVENTS: dict[str, tuple[str, str]] = { + "no_write": ("auth_failure", "GitHub refused the token a push to {repo}"), + "credential_rejected": ("auth_failure", "GitHub did not accept a token for {repo}"), + "org_policy": ("auth_failure", "An organization policy blocks the token for {repo}"), + "archived": ("unknown_environmental", "{repo} is archived on GitHub (read-only)"), +} class _TokenRemedy(NamedTuple): - kind: str # the token type, as the error names it + label: str # the token type, as the error names it remedy: str @@ -219,7 +241,8 @@ def _token_remedy(token: str, repo_url: str) -> _TokenRemedy: if token.startswith("github_pat_"): return _TokenRemedy( "fine-grained personal access token", - f"give the token the Contents permission with Read and write access on {repo_url}", + f"include {repo_url} in the token's repository access and give it the " + "Contents permission with Read and write access", ) if token.startswith("ghp_"): return _TokenRemedy("classic personal access token", "give the token the `repo` scope") @@ -231,69 +254,82 @@ def _token_remedy(token: str, repo_url: str) -> _TokenRemedy: ) return _TokenRemedy( "GitHub token", - "use a fine-grained personal access token with the Contents permission with " - f"Read and write access on {repo_url}, or a classic one with the `repo` scope", + f"use a fine-grained personal access token with access to {repo_url} and the " + "Contents permission with Read and write access, or a classic one with the " + "`repo` scope", ) -def _matching_line(stderr: str, signatures: tuple[str, ...]) -> str: - """The first stderr line naming one of *signatures*, redacted: the line that - says why, not a ``warning:`` git may print before it.""" +def _quoted_line(lines: list[str], signatures: tuple[str, ...]) -> str: + """The first line naming one of *signatures*, as the error quotes it: the line + that says why, not a ``warning:`` before it. Redacted, and without the login + GitHub names in ``denied to ``.""" from shell import redact_secrets - lines = [ln.strip() for ln in stderr.splitlines() if ln.strip()] line = next((ln for ln in lines if any(s in ln.lower() for s in signatures)), "") - return redact_secrets((line or (lines[0] if lines else ""))[:200]) + line = re.sub(r"(?i)(denied to )\S+", r"\1", line or (lines[0] if lines else "")) + return redact_secrets(line[:200]) def _push_refusal(config: TaskConfig, stderr: str) -> PushCapabilityError | None: - """Classify a refused dry-run push; ``None`` when GitHub did not refuse it.""" + """Classify a failed dry-run push; ``None`` when GitHub did not refuse it.""" from progress_writer import format_blocker_reason + from shell import is_transient_cmd_failure + # A failure that outlasted the retries or a blocked host is never a refusal, so + # a policy phrase can never make it permanent; _fail_setup_command takes it. + if is_transient_cmd_failure(stderr): + return None + lines = [ln.strip() for ln in stderr.splitlines() if ln.strip()] + remote = " ".join(ln.lower() for ln in lines if ln.lower().startswith("remote:")) low = stderr.lower() repo_url = config.repo_url no_loss = "The task stopped before the agent ran, so no work was lost." + if _ARCHIVED_SIGNATURE in remote: + return PushCapabilityError( + f"Repository {repo_url} is archived on GitHub, so it is read-only " + f"({_quoted_line(lines, (_ARCHIVED_SIGNATURE,))}). Unarchive it or target " + f"another repository. {no_loss}", + cause="archived", + ) + for signature, cause in _ORG_POLICY_REFUSALS: + if signature in remote: + return PushCapabilityError( + f"GitHub organization policy blocks pushes to {repo_url}: {cause} " + f"({_quoted_line(lines, (signature,))}). {no_loss}", + cause="org_policy", + ) if any(sig in low for sig in _CREDENTIAL_REJECTED_SIGNATURES): - line = _matching_line(stderr, _CREDENTIAL_REJECTED_SIGNATURES) + line = _quoted_line(lines, _CREDENTIAL_REJECTED_SIGNATURES) return PushCapabilityError( format_blocker_reason( "auth_failure", - f"GitHub rejected the token when asked to push ({line}): it is invalid, " - f"expired or revoked. Replace the GitHub token secret, then resubmit. {no_loss}", + f"GitHub did not accept a token for the push ({line}): it is missing, " + f"invalid, expired or revoked. Replace the GitHub token secret, then " + f"resubmit. {no_loss}", repo_url, - ) - ) - if "archived" in low: - line = _matching_line(stderr, ("archived",)) - return PushCapabilityError( - f"Cannot push to {repo_url}: GitHub reports the repository is archived, so it " - f"is read-only ({line}). Unarchive it or target another repository. {no_loss}" + ), + cause="credential_rejected", ) - for signature, cause in _ORG_POLICY_REFUSALS: - if signature in low: - line = _matching_line(stderr, (signature,)) - return PushCapabilityError( - f"Token cannot push to {repo_url}: {cause} ({line}). {no_loss}" - ) if any(sig in low for sig in _PUSH_REFUSED_SIGNATURES): - line = _matching_line(stderr, _PUSH_REFUSED_SIGNATURES) token_type, remedy = _token_remedy(config.github_token, repo_url) return PushCapabilityError( - f"Token cannot push to {repo_url}: the {token_type} can read the " - f"repository, but GitHub refused it write access ({line}). To fix it, " + f"Token cannot push to {repo_url}: GitHub refused the {token_type} write " + f"access ({_quoted_line(lines, _PUSH_REFUSED_SIGNATURES)}). To fix it, " f"{remedy}. {no_loss} Token types and the permissions they need: " - "agent/README.md, GitHub PAT — Minimal Permissions." + "agent/README.md, GitHub PAT — Minimal Permissions.", + cause="no_write", ) return None def _preflight_probe_commit(repo_dir: str) -> str: - """A commit to dry-run push that every clone has, an empty repository's too. + """Make a commit to dry-run push, in any clone, an empty repository's too. ``HEAD`` names no commit in a clone of an empty repository, so pushing it fails - before git contacts the remote. This commit, of the empty tree, exists in any - clone; making it writes one unreferenced object and leaves ``HEAD``, the index - and the working tree alone.""" + before git contacts the remote. This commit's tree is the empty tree, which git + knows without storing it, so making the commit writes one unreferenced object and + leaves ``HEAD``, the index and the working tree alone.""" tree = run_cmd( ["git", "hash-object", "-t", "tree", "/dev/null"], label="push-preflight-tree", @@ -320,6 +356,56 @@ def _preflight_probe_commit(repo_dir: str) -> str: _PUSH_PREFLIGHT_TIMEOUT_S = 120 +def _fail_push_preflight_timeout( + config: TaskConfig, exc: subprocess.TimeoutExpired, progress: Any +) -> NoReturn: + """Report a dry run GitHub did not answer in time: retryable, not a build timeout. + + ``run_cmd_with_backoff`` does not retry a timeout, so the reason says one attempt + rather than claiming retries.""" + from hooks import _record_blocker_reason, _try_progress + from progress_writer import format_blocker_reason + from shell import redact_secrets + + output = exc.stderr.decode(errors="replace") if isinstance(exc.stderr, bytes) else exc.stderr + if output: + log("WARN", f"push-preflight output before the timeout: {redact_secrets(output[-500:])}") + detail = f"push-preflight got no answer from GitHub within {_PUSH_PREFLIGHT_TIMEOUT_S}s" + _record_blocker_reason("dependency_unreachable", detail, config.repo_url) + if progress is not None: + _try_progress( + progress, + "write_agent_blocked", + kind="dependency_unreachable", + detail=detail, + remediation_hint="Check GitHub's status and the agent VPC's reachability, then retry.", + retryable=True, + resource=config.repo_url, + ) + raise DependencyUnreachableError( + format_blocker_reason("dependency_unreachable", detail, config.repo_url) + ) + + +def _report_refusal(refusal: PushCapabilityError, config: TaskConfig, progress: Any) -> None: + """Emit the live ``agent_blocked`` event that matches *refusal*'s cause.""" + from hooks import _record_blocker_reason, _try_progress + + kind, detail = _REFUSAL_EVENTS[refusal.cause] + detail = detail.format(repo=config.repo_url) + _record_blocker_reason(kind, detail, config.repo_url) + if progress is not None: + _try_progress( + progress, + "write_agent_blocked", + kind=kind, + detail=detail, + remediation_hint="The task error names the cause and the fix; resubmit after it.", + retryable=False, + resource=config.repo_url, + ) + + def _preflight_push_capability(config: TaskConfig, repo_dir: str, progress: Any) -> None: """Fail the task now if GitHub refuses the token a push to the repository (#801). @@ -355,7 +441,8 @@ def _preflight_push_capability(config: TaskConfig, repo_dir: str, progress: Any) "push", "--dry-run", # A dry run still runs the pre-push hook. Skip it: the probe tests the - # credential, and no hook a hook manager or core.hooksPath set up runs. + # credential, and no hook from a global core.hooksPath or a git + # template may block or slow it. "--no-verify", "origin", f"+{probe}:{_PUSH_PREFLIGHT_REF}", @@ -365,35 +452,15 @@ def _preflight_push_capability(config: TaskConfig, repo_dir: str, progress: Any) timeout=_PUSH_PREFLIGHT_TIMEOUT_S, on_retry=_clone_backoff_reporter(progress, "push-preflight"), ) - except subprocess.TimeoutExpired: - # Unhandled, the timeout would surface as a build timeout. It is GitHub or the - # network that did not answer: report it as the retryable transient it is. - _fail_setup_command( - "push-preflight", - config.repo_url, - f"operation timed out after {_PUSH_PREFLIGHT_TIMEOUT_S}s", - progress, - ) + except subprocess.TimeoutExpired as exc: + # Unhandled, the timeout would be classified as a build timeout. + _fail_push_preflight_timeout(config, exc, progress) if result.returncode == 0: return stderr = result.stderr or "" refusal = _push_refusal(config, stderr) if refusal is not None: - if progress is not None: - from hooks import _try_progress - - _try_progress( - progress, - "write_agent_blocked", - kind="auth_failure", - detail=f"GitHub refused the token a push to {config.repo_url}", - remediation_hint=( - "See the task error for the cause and the fix, then resubmit. The " - "agent never widens its own credentials." - ), - retryable=False, - resource=config.repo_url, - ) + _report_refusal(refusal, config, progress) raise refusal # Not a refusal: a transient failure that outlasted the retries, an egress block, # or another git error. The final push goes through the same remote, credential diff --git a/agent/src/shell.py b/agent/src/shell.py index 8467855dc..5453e4499 100644 --- a/agent/src/shell.py +++ b/agent/src/shell.py @@ -413,6 +413,7 @@ def run_cmd( "502 bad gateway", "504 gateway", "429 too many requests", + "the requested url returned error: 429", # git's form of a rate limit "eai_again", "network is unreachable", "tls handshake timeout", diff --git a/agent/tests/test_repo.py b/agent/tests/test_repo.py index 9d91c0614..a3c6abd46 100644 --- a/agent/tests/test_repo.py +++ b/agent/tests/test_repo.py @@ -850,25 +850,33 @@ def __call__(self, cmd, label, cwd=None, timeout=600, check=True, **kwargs): if label == "push-preflight": self.preflight_timeout = timeout if self._timeout: - raise subprocess.TimeoutExpired(cmd, timeout) + raise subprocess.TimeoutExpired(cmd, timeout, stderr=b"stalled") return SimpleNamespace( returncode=self._preflight_rc, stdout="", stderr=self._preflight_stderr ) return result -# What GitHub prints when it refuses a push. The first is what the scope-less -# classic PAT of #801 produced; the second is the 404 GitHub can send instead of a -# 403. -_DENIED_403 = ( - "remote: Permission to owner/repo.git denied to someone.\n" - "fatal: unable to access 'https://github.com/owner/repo.git/': " - "The requested URL returned error: 403" -) +def _denied_403(repo_url="owner/repo", user="someone"): + # A push without write access, as seen by hand against a public repository. + return ( + f"remote: Permission to {repo_url}.git denied to {user}.\n" + f"fatal: unable to access 'https://github.com/{repo_url}.git/': " + "The requested URL returned error: 403" + ) + + +_DENIED_403 = _denied_403() +# The 404 #801 reports for every write of the scope-less classic PAT. _DENIED_404 = ( "remote: Repository not found.\n" "fatal: repository 'https://github.com/owner/repo.git/' not found" ) +_DENIED_FINE_GRAINED = ( + "remote: Write access to repository not granted.\n" + "fatal: unable to access 'https://github.com/owner/repo.git/': " + "The requested URL returned error: 403" +) _REJECTED_401 = ( "remote: Invalid username or token. Password authentication is not supported.\n" "fatal: Authentication failed for 'https://github.com/owner/repo.git/'" @@ -884,6 +892,17 @@ def __call__(self, cmd, label, cwd=None, timeout=600, check=True, **kwargs): "fatal: unable to access 'https://github.com/owner/repo.git/': " "The requested URL returned error: 403" ) +_IP_ALLOW_LIST = ( + "remote: Although you appear to have the correct authorization credentials, the " + "`acme` organization has an IP allow list enabled, and your IP address is not " + "permitted to access this resource.\n" + "fatal: unable to access 'https://github.com/owner/repo.git/': " + "The requested URL returned error: 403" +) +_BAD_GATEWAY = ( + "fatal: unable to access 'https://github.com/{repo}.git/': " + "The requested URL returned error: 502" +) class TestPushCapabilityPreflight: @@ -899,20 +918,21 @@ def _setup(self, monkeypatch, fake): _patch_common(monkeypatch, fake) monkeypatch.setattr(repo, "detect_default_branch", lambda url, d: "main") - def _raises(self, monkeypatch, stderr, exc=None, **config): + def _raises(self, monkeypatch, stderr, exc=None, progress=None, **config): import pytest fake = _PreflightFake(preflight_rc=128, preflight_stderr=stderr) self._setup(monkeypatch, fake) with pytest.raises(exc or repo.PushCapabilityError) as excinfo: - repo.setup_repo(_config(**config)) + repo.setup_repo(_config(**config), progress=progress) return fake, str(excinfo.value) def test_writeable_task_probes_push_with_a_forced_dry_run(self, monkeypatch): + token = "ghp_" + "z" * 36 fake = _PreflightFake() self._setup(monkeypatch, fake) - setup = repo.setup_repo(_config(branch_name="bgagent/task-abc/feature")) + setup = repo.setup_repo(_config(branch_name="bgagent/task-abc/feature", github_token=token)) cmd = fake.cmd_for("push-preflight") assert cmd is not None @@ -927,7 +947,7 @@ def test_writeable_task_probes_push_with_a_forced_dry_run(self, monkeypatch): assert dst.startswith("refs/heads/") assert dst != f"refs/heads/{setup.branch}" # The credential comes from the helper at call time, never the argv. - assert "ghp_" not in " ".join(cmd) + assert token not in " ".join(cmd) assert "@" not in " ".join(cmd) assert fake.preflight_timeout == 120 @@ -947,13 +967,18 @@ def test_read_only_workflow_is_not_gated(self, monkeypatch): fake = _PreflightFake(preflight_rc=128, preflight_stderr=_DENIED_403) self._setup(monkeypatch, fake) + def _no_probe(repo_dir): + raise AssertionError("a read-only task must not make the probe commit") + + monkeypatch.setattr(repo, "_preflight_probe_commit", _no_probe) + repo.setup_repo(_config(read_only=True)) assert "push-preflight" not in fake.labels() - def test_read_only_matches_the_shipped_workflows_that_never_push(self): + def test_read_only_matches_the_coding_workflows_that_never_push(self): # The skip keys on read_only; the issue's rule is "never pushes". Tie the - # two together for the workflows the image ships. + # two together for the coding workflows the image ships. from workflow import load_workflow assert load_workflow("coding/pr-review-v1").read_only is True @@ -961,7 +986,7 @@ def test_read_only_matches_the_shipped_workflows_that_never_push(self): assert load_workflow(pushing).read_only is False, pushing def test_fine_grained_token_passes_on_the_servers_verdict(self, monkeypatch): - # A fine-grained PAT gets no X-OAuth-Scopes header back from GitHub; the dry + # GitHub returns no X-OAuth-Scopes header for a fine-grained PAT; the dry # run reads no scopes, so it passes on the server's verdict alone. fake = _PreflightFake(preflight_rc=0) self._setup(monkeypatch, fake) @@ -980,31 +1005,35 @@ def test_classic_token_with_repo_scope_passes(self, monkeypatch): def test_classic_token_without_scopes_fails_before_the_agent_runs(self, monkeypatch): token = "ghp_" + "b" * 36 - fake, message = self._raises(monkeypatch, _DENIED_403, github_token=token) + fake, message = self._raises(monkeypatch, _DENIED_404, github_token=token) # The CDK error classifier maps this phrase to "Insufficient GitHub token # scopes" (cdk/src/handlers/shared/error-classifier.ts). assert message.startswith("Token cannot push to owner/repo") assert "classic personal access token" in message assert "`repo` scope" in message - assert "Permission to owner/repo.git denied" in message + assert "Repository not found" in message assert "agent/README.md" in message assert token not in message # No later setup step ran: no branch, no mise install, no build. assert fake.labels()[-1] == "push-preflight" - def test_404_after_a_successful_clone_is_a_refusal(self, monkeypatch): - # The clone just read this repository with the same credential, so "not - # found" on the push means the token may not write to it. - _, message = self._raises(monkeypatch, _DENIED_404, github_token="ghp_" + "b" * 36) + def test_403_refusal_and_the_login_is_not_kept(self, monkeypatch): + _, message = self._raises(monkeypatch, _denied_403(user="bot-account")) assert message.startswith("Token cannot push to owner/repo") + assert "Permission to owner/repo.git denied to " in message + assert "bot-account" not in message - def test_fine_grained_refusal_names_the_contents_permission(self, monkeypatch): - _, message = self._raises(monkeypatch, _DENIED_403, github_token="github_pat_" + "c" * 20) + def test_fine_grained_refusal_names_access_and_the_contents_permission(self, monkeypatch): + _, message = self._raises( + monkeypatch, _DENIED_FINE_GRAINED, github_token="github_pat_" + "c" * 20 + ) assert "fine-grained personal access token" in message + assert "include owner/repo in the token's repository access" in message assert "Contents permission with Read and write access" in message + assert "Write access to repository not granted" in message def test_unknown_token_type_gets_both_remedies(self, monkeypatch): # No token in the config: gh supplies whatever it is logged in with. @@ -1016,36 +1045,72 @@ def test_unknown_token_type_gets_both_remedies(self, monkeypatch): def test_github_app_token_remedy(self): remedy = repo._token_remedy("ghs_" + "e" * 36, "owner/repo") - assert remedy.kind == "GitHub App token" + assert remedy.label == "GitHub App token" assert "install it on owner/repo" in remedy.remedy def test_rejected_credential_is_an_auth_failure_not_a_scope_problem(self, monkeypatch): - # A revoked or expired token: a public repository cloned without it, but - # GitHub rejects it at the push. Adding scopes would not help. + # A token revoked or expired after the clone: GitHub rejects it at the push. + # Adding scopes would not help. _, message = self._raises(monkeypatch, _REJECTED_401, github_token="ghp_" + "f" * 36) assert message.startswith("BLOCKED[auth_failure]:") assert "(resource: owner/repo)" in message assert "invalid, expired or revoked" in message assert "Token cannot push" not in message - assert "can read the repository" not in message def test_archived_repository_is_not_blamed_on_the_token(self, monkeypatch): _, message = self._raises(monkeypatch, _ARCHIVED, github_token="ghp_" + "b" * 36) - assert message.startswith("Cannot push to owner/repo") - assert "archived" in message - # Not the phrase the classifier reads as a token-scope problem. + assert message.startswith("Repository owner/repo is archived on GitHub, so it is read-only") assert "Token cannot push" not in message assert "`repo` scope" not in message def test_saml_enforcement_names_sso_authorization(self, monkeypatch): _, message = self._raises(monkeypatch, _SAML, github_token="ghp_" + "b" * 36) - assert message.startswith("Token cannot push to owner/repo") + assert message.startswith("GitHub organization policy blocks pushes to owner/repo") assert "SAML single sign-on" in message + assert "Configure SSO" in message assert "`repo` scope" not in message + def test_ip_allow_list_names_the_allow_list(self, monkeypatch): + _, message = self._raises(monkeypatch, _IP_ALLOW_LIST) + + assert message.startswith("GitHub organization policy blocks pushes to owner/repo") + assert "egress IP addresses" in message + + def test_names_never_pick_the_cause(self, monkeypatch): + import pytest + + # The policy words in a user or repository name must not pass for GitHub's + # message: these are plain refusals of a scope-less classic token. + for repo_url, user in ( + ("acme/archived-tools", "someone"), + ("acme/python3-saml", "someone"), + ("owner/repo", "samlee"), + ("owner/repo", "archivedbot"), + ): + _, message = self._raises( + monkeypatch, + _denied_403(repo_url, user), + repo_url=repo_url, + github_token="ghp_" + "b" * 36, + ) + assert message.startswith(f"Token cannot push to {repo_url}"), repo_url + assert "`repo` scope" in message + assert "SAML" not in message + assert "is archived on GitHub" not in message + + # Nor turn a GitHub outage on such a repository into a permanent refusal. + for repo_url in ("acme/archived-notes", "acme/saml-tools"): + fake = _PreflightFake( + preflight_rc=128, preflight_stderr=_BAD_GATEWAY.format(repo=repo_url) + ) + self._setup(monkeypatch, fake) + with pytest.raises(repo.DependencyUnreachableError) as excinfo: + repo.setup_repo(_config(repo_url=repo_url)) + assert str(excinfo.value).startswith("BLOCKED[dependency_unreachable]:"), repo_url + def test_error_quotes_the_line_that_says_why(self, monkeypatch): stderr = "warning: redirecting to https://github.com/owner/repo.git/\n" + _DENIED_403 _, message = self._raises(monkeypatch, stderr) @@ -1056,34 +1121,43 @@ def test_error_quotes_the_line_that_says_why(self, monkeypatch): def test_git_stderr_is_redacted_in_the_error(self, monkeypatch): leaked = "ghp_" + "d" * 36 _, message = self._raises( - monkeypatch, f"remote: Permission to owner/repo.git denied to {leaked}." + monkeypatch, f"remote: Permission to owner/repo.git denied. Token {leaked}" ) assert leaked not in message - def test_refusal_is_reported_on_the_live_stream(self, monkeypatch): - import pytest - - fake = _PreflightFake(preflight_rc=128, preflight_stderr=_DENIED_403) - self._setup(monkeypatch, fake) - progress = _RecordingProgress() - - with pytest.raises(repo.PushCapabilityError): - repo.setup_repo(_config(), progress=progress) + def test_each_refusal_emits_the_event_of_its_cause(self, monkeypatch): + for stderr, kind in ( + (_DENIED_403, "auth_failure"), + (_REJECTED_401, "auth_failure"), + (_SAML, "auth_failure"), + (_ARCHIVED, "unknown_environmental"), + ): + progress = _RecordingProgress() + self._raises(monkeypatch, stderr, progress=progress) - blocked = [kw for name, kw in progress.calls if name == "write_agent_blocked"] - assert len(blocked) == 1 - assert blocked[0]["kind"] == "auth_failure" - assert blocked[0]["retryable"] is False - assert blocked[0]["resource"] == "owner/repo" + blocked = [kw for name, kw in progress.calls if name == "write_agent_blocked"] + assert len(blocked) == 1, stderr + assert blocked[0]["kind"] == kind, stderr + assert blocked[0]["retryable"] is False + assert blocked[0]["resource"] == "owner/repo" + # An archived repository is not reported as the token's fault. + assert "token" not in blocked[0]["detail"].lower() def test_transient_failure_is_not_reported_as_a_permission_problem(self, monkeypatch): # Simulates GitHub staying unavailable after the retries: a retryable # blocker, so the operator is not sent to change a token that is fine. + _, message = self._raises( + monkeypatch, _BAD_GATEWAY.format(repo="owner/repo"), exc=repo.DependencyUnreachableError + ) + + assert message.startswith("BLOCKED[dependency_unreachable]:") + + def test_rate_limit_is_transient(self, monkeypatch): _, message = self._raises( monkeypatch, "fatal: unable to access 'https://github.com/owner/repo.git/': " - "The requested URL returned error: 502", + "The requested URL returned error: 429", exc=repo.DependencyUnreachableError, ) @@ -1094,19 +1168,26 @@ def test_timeout_is_a_retryable_dependency_failure_not_a_build_timeout(self, mon fake = _PreflightFake(timeout=True) self._setup(monkeypatch, fake) + progress = _RecordingProgress() # Unhandled, TimeoutExpired would be classified "Build/tests didn't finish". with pytest.raises(repo.DependencyUnreachableError) as excinfo: - repo.setup_repo(_config()) + repo.setup_repo(_config(), progress=progress) - assert str(excinfo.value).startswith("BLOCKED[dependency_unreachable]:") + message = str(excinfo.value) + assert message.startswith("BLOCKED[dependency_unreachable]:") + assert "within 120s" in message + assert "retries" not in message + blocked = [kw for name, kw in progress.calls if name == "write_agent_blocked"] + assert blocked and blocked[0]["retryable"] is True def test_unresolvable_host_is_an_egress_block(self, monkeypatch): _, message = self._raises( monkeypatch, - "fatal: unable to access 'https://github.com/owner/repo.git/': " + "fatal: unable to access 'https://github.com/acme/archived-x.git/': " "Could not resolve host: github.com", exc=repo.DependencyUnreachableError, + repo_url="acme/archived-x", ) assert message.startswith("BLOCKED[egress_denied]:") @@ -1120,6 +1201,23 @@ def test_other_failure_stops_the_task_with_the_git_error(self, monkeypatch): assert "push-preflight failed" in message assert "something unexpected" in message + def test_failed_probe_commit_stops_setup_before_the_push(self, monkeypatch): + import pytest + + fake = _PreflightFake() + self._setup(monkeypatch, fake) + + def _broken(repo_dir): + raise RuntimeError("push-preflight-commit failed (exit 128): fatal: bad object") + + monkeypatch.setattr(repo, "_preflight_probe_commit", _broken) + + with pytest.raises(RuntimeError, match="push-preflight-commit failed"): + repo.setup_repo(_config()) + + assert "push-preflight" not in fake.labels() + assert "create-branch" not in fake.labels() + def test_pr_iteration_is_checked_before_its_branch_is_fetched(self, monkeypatch): # pr-iteration and restack push their PR branch too (push_resolve). fake, _ = self._raises( @@ -1141,9 +1239,55 @@ def test_stacked_child_is_checked_before_its_base_is_fetched(self, monkeypatch): assert "fetch-base-branch" not in fake.labels() +class TestPushPreflightRetries: + """Through the real bounded retry loop: a refusal fails in one attempt, an + outage is retried.""" + + def _run(self, monkeypatch, stderr): + import pytest + + attempts = [] + + def fake_run_cmd(cmd, label, cwd=None, timeout=600, check=True, **kwargs): + if label == "push-preflight": + attempts.append(cmd) + return SimpleNamespace(returncode=128, stdout="", stderr=stderr) + return SimpleNamespace(returncode=0, stdout="", stderr="") + + import functools + + import shell + + sleeps = [] + monkeypatch.setattr("shell.run_cmd", fake_run_cmd) + # The real loop, with its sleeps recorded rather than slept. + monkeypatch.setattr( + repo, + "run_cmd_with_backoff", + functools.partial(shell.run_cmd_with_backoff, sleep=sleeps.append), + ) + monkeypatch.setattr(repo, "_preflight_probe_commit", lambda repo_dir: _PROBE_SHA) + with pytest.raises(RuntimeError): + repo._preflight_push_capability(_config(), "/nonexistent", progress=None) + return attempts, sleeps + + def test_refusal_takes_one_attempt(self, monkeypatch): + attempts, sleeps = self._run(monkeypatch, _DENIED_403) + + assert len(attempts) == 1 + assert sleeps == [] + + def test_outage_is_retried(self, monkeypatch): + attempts, sleeps = self._run(monkeypatch, _BAD_GATEWAY.format(repo="owner/repo")) + + assert len(attempts) == 3 + assert len(sleeps) == 2 + + class TestPushPreflightAgainstRealGit: """The preflight's commands against a real git remote (a local bare repository): - it passes, changes nothing, and does not depend on HEAD or on hooks.""" + it reaches the remote, passes, changes nothing, and does not depend on HEAD or on + hooks.""" @staticmethod def _git(*args, cwd): @@ -1162,7 +1306,7 @@ def _remote_and_clone(self, tmp_path, monkeypatch, *, empty=False): seed = tmp_path / "seed" self._git("init", "-q", str(seed), cwd=tmp_path) self._git("commit", "-q", "--allow-empty", "-m", "init", cwd=seed) - self._git("push", "-q", str(remote), "HEAD:refs/heads/main", cwd=tmp_path / "seed") + self._git("push", "-q", str(remote), "HEAD:refs/heads/main", cwd=seed) work = tmp_path / "work" self._git("clone", "-q", str(remote), str(work), cwd=tmp_path) return remote, work @@ -1181,6 +1325,17 @@ def test_dry_run_creates_no_ref_and_leaves_the_clone_alone(self, tmp_path, monke assert self._git("status", "--porcelain", cwd=work) == "" assert (work / ".git" / "config").read_text() == config_before + def test_dry_run_reaches_the_remote(self, tmp_path, monkeypatch): + import pytest + + # The check rests on the dry run contacting the remote: with no remote to + # reach, it must fail, not pass locally. + _, work = self._remote_and_clone(tmp_path, monkeypatch) + self._git("remote", "set-url", "origin", str(tmp_path / "missing.git"), cwd=work) + + with pytest.raises(RuntimeError, match="push-preflight failed"): + repo._preflight_push_capability(_config(), str(work), progress=None) + def test_empty_repository_passes(self, tmp_path, monkeypatch): # HEAD names no commit in a clone of an empty repository; the probe commit # does not need one. @@ -1205,10 +1360,22 @@ def test_existing_ref_with_the_probe_name_does_not_block(self, tmp_path, monkeyp def test_pre_push_hook_does_not_run(self, tmp_path, monkeypatch): _, work = self._remote_and_clone(tmp_path, monkeypatch) + hooks = tmp_path / "hooks" + hooks.mkdir() marker = tmp_path / "hook-ran" - hook = work / ".git" / "hooks" / "pre-push" + hook = hooks / "pre-push" hook.write_text(f"#!/bin/sh\ntouch {marker}\nexit 1\n") hook.chmod(0o755) + # Pin the hooks directory so a hooksPath from the host cannot hide the hook. + self._git("config", "core.hooksPath", str(hooks), cwd=work) + # Control: a plain dry run does run it. + subprocess.run( + ["git", "push", "--dry-run", "origin", "HEAD:refs/heads/x"], + cwd=work, + capture_output=True, + ) + assert marker.exists() + marker.unlink() repo._preflight_push_capability(_config(), str(work), progress=None) diff --git a/agent/tests/test_shell.py b/agent/tests/test_shell.py index 1424678e4..79507677d 100644 --- a/agent/tests/test_shell.py +++ b/agent/tests/test_shell.py @@ -87,6 +87,8 @@ def test_dns_and_5xx_are_transient(self): assert is_transient_cmd_failure("fatal: Could not resolve host: github.com") assert is_transient_cmd_failure("The requested URL returned error: 503") assert is_transient_cmd_failure("npm ERR! 429 Too Many Requests") + # git prints a rate limit as the status code alone (#801: the push preflight). + assert is_transient_cmd_failure("The requested URL returned error: 429") assert is_transient_cmd_failure("getaddrinfo EAI_AGAIN registry.npmjs.org") def test_permanent_failures_are_not_transient(self): diff --git a/cdk/src/handlers/shared/error-classifier.ts b/cdk/src/handlers/shared/error-classifier.ts index 8d6b29c14..730ffaf1a 100644 --- a/cdk/src/handlers/shared/error-classifier.ts +++ b/cdk/src/handlers/shared/error-classifier.ts @@ -125,6 +125,31 @@ const PATTERNS: readonly ErrorPattern[] = [ errorClass: ErrorClass.USER, }, }, + { + // The agent's push preflight (agent/src/repo.py): SAML SSO or an IP allow list + // blocks the token, which scopes would not fix. + pattern: /GitHub organization policy blocks pushes to/i, + classification: { + category: ErrorCategory.AUTH, + title: 'GitHub organization policy blocks the token', + description: 'The organization that owns the repository enforces SAML single sign-on or an IP allow list, and the GitHub token does not satisfy it.', + remedy: 'Do what the error detail names: authorize the token for the organization\'s SAML single sign-on, or add the agent\'s egress IP addresses to the organization\'s IP allow list. Then resubmit.', + retryable: false, + errorClass: ErrorClass.SERVICE, + }, + }, + { + // The agent's push preflight: no token change makes an archived repository writable. + pattern: /is archived on GitHub, so it is read-only/i, + classification: { + category: ErrorCategory.CONFIG, + title: 'Repository is archived', + description: 'The repository is archived on GitHub, so nothing can be pushed to it.', + remedy: 'Unarchive the repository on GitHub, or submit the task against another repository.', + retryable: false, + errorClass: ErrorClass.USER, + }, + }, { pattern: /Token cannot (push to|interact with pull requests on)/i, classification: { diff --git a/cdk/test/handlers/shared/error-classifier.test.ts b/cdk/test/handlers/shared/error-classifier.test.ts index 2b46c65c1..9459e21ec 100644 --- a/cdk/test/handlers/shared/error-classifier.test.ts +++ b/cdk/test/handlers/shared/error-classifier.test.ts @@ -89,35 +89,45 @@ describe('classifyError', () => { }); // The errors agent/src/repo.py raises (PushCapabilityError) when GitHub refuses - // the dry-run push, in the form the pipeline persists them: prefixed with the - // exception's type name. + // the dry-run push, verbatim as the pipeline persists them (prefixed with the + // exception's type name), printed from the agent code for #801's test cases. test.each([ - ['remote denial', 'remote: Permission to owner/repo.git denied to someone.'], - ['HTTP 403', 'fatal: unable to access \'https://github.com/owner/repo.git/\': The requested URL returned error: 403'], - ])('classifies the agent push preflight refusal quoting a %s line as insufficient token scopes (#801)', (_label, gitLine) => { - // The git line embedded in it ("denied", "403") must not move it to another title. - const result = classifyError( - 'PushCapabilityError: Token cannot push to owner/repo: the classic personal access ' - + `token can read the repository, but GitHub refused it write access (${gitLine}). ` - + 'To fix it, give the token the `repo` scope. The task stopped before the agent ran, ' - + 'so no work was lost. Token types and the permissions they need: agent/README.md, ' - + 'GitHub PAT — Minimal Permissions.', - ); - expect(result!.category).toBe(ErrorCategory.AUTH); - expect(result!.title).toBe('Insufficient GitHub token scopes'); - expect(result!.retryable).toBe(false); - }); - - test('classifies the agent push preflight credential rejection as an auth blocker (#801)', () => { - const result = classifyError( - 'PushCapabilityError: BLOCKED[auth_failure]: GitHub rejected the token when asked to ' - + 'push (fatal: Authentication failed for \'https://github.com/owner/repo.git/\'): it is ' - + 'invalid, expired or revoked. Replace the GitHub token secret, then resubmit. The task ' - + 'stopped before the agent ran, so no work was lost. (resource: owner/repo)', - ); - expect(result!.category).toBe(ErrorCategory.BLOCKED); - expect(result!.title).toBe('Blocked: authentication rejected'); - expect(result!.description).toContain('owner/repo'); + [ + 'a token without write access', + 'PushCapabilityError: Token cannot push to owner/repo: GitHub refused the classic personal access token write access (remote: Permission to owner/repo.git denied to ). To fix it, give the token the `repo` scope. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.', + ErrorCategory.AUTH, + 'Insufficient GitHub token scopes', + ], + [ + 'a rejected credential', + 'PushCapabilityError: BLOCKED[auth_failure]: GitHub did not accept a token for the push (remote: Invalid username or token. Password authentication is not supported.): it is missing, invalid, expired or revoked. Replace the GitHub token secret, then resubmit. The task stopped before the agent ran, so no work was lost. (resource: owner/repo)', + ErrorCategory.BLOCKED, + 'Blocked: authentication rejected', + ], + [ + 'an archived repository', + 'PushCapabilityError: Repository owner/repo is archived on GitHub, so it is read-only (remote: This repository was archived so it is read-only.). Unarchive it or target another repository. The task stopped before the agent ran, so no work was lost.', + ErrorCategory.CONFIG, + 'Repository is archived', + ], + [ + 'SAML SSO enforcement', + "PushCapabilityError: GitHub organization policy blocks pushes to owner/repo: it enforces SAML single sign-on and the token is not authorized for it. To fix it, authorize the classic token for the organization (GitHub > Settings > Developer settings > Personal access tokens > Tokens (classic) > Configure SSO) (remote: The 'acme' organization has enabled or enforced SAML SSO.). The task stopped before the agent ran, so no work was lost.", + ErrorCategory.AUTH, + 'GitHub organization policy blocks the token', + ], + [ + 'an IP allow list', + "PushCapabilityError: GitHub organization policy blocks pushes to owner/repo: its IP allow list does not include the agent's address. To fix it, add the agent's egress IP addresses to the organization's IP allow list (remote: Although you appear to have the correct authorization credentials, the `acme` organization has an IP allow list enabled, and your IP address is not permitted to access this resource.). The task stopped before the agent ran, so no work was lost.", + ErrorCategory.AUTH, + 'GitHub organization policy blocks the token', + ], + ])('classifies the agent push preflight refusal for %s (#801)', (_label, message, category, title) => { + // The git line quoted in each ("denied", "403", "credentials") must not move it + // to another title, and none gets the scope remedy unless scopes are the cause. + const result = classifyError(message); + expect(result!.category).toBe(category); + expect(result!.title).toBe(title); expect(result!.retryable).toBe(false); }); diff --git a/docs/design/SECURITY.md b/docs/design/SECURITY.md index d30e5d335..46d5a3aaa 100644 --- a/docs/design/SECURITY.md +++ b/docs/design/SECURITY.md @@ -154,8 +154,8 @@ flowchart LR | Admission | Concurrency limit | `orchestrator.ts` | `admission_queued` event | | Pre-flight | GitHub access, PAT permissions, PR access | `preflight.ts` | `preflight_failed` event | | Hydration | Guardrail prompt screening | `context-hydration.ts` | `guardrail_blocked` event | -| Repo setup | GitHub token may push (dry-run push, skipped for read-only workflows) | `agent/src/repo.py` | `agent_blocked` event, task `FAILED` before the agent runs | | Hydration | Budget/quota resolution | `orchestrator.ts` | Persisted on task record | +| Repo setup | GitHub token may push (dry-run push, skipped for read-only workflows) | `agent/src/repo.py` | `agent_blocked` event, task `FAILED` before the agent runs | | Execution | Tool-call policy (Cedar) | `agent/src/hooks.py`, `agent/src/policy.py` | `POLICY_DECISION` telemetry | | Execution | Output secret screening | `agent/src/output_scanner.py` | `OUTPUT_SCREENING` telemetry | | Execution | Turn/cost budget | Claude Agent SDK | Cost in task result | diff --git a/docs/guides/USER_GUIDE.md b/docs/guides/USER_GUIDE.md index 7f4dbf08c..510d19de9 100644 --- a/docs/guides/USER_GUIDE.md +++ b/docs/guides/USER_GUIDE.md @@ -1192,7 +1192,7 @@ The agent is only as good as the context it receives. A well-prepared repository - **Onboard first** - Repositories must be registered via a Blueprint construct before tasks can target them. If you get a `REPO_NOT_ONBOARDED` error, contact your platform administrator. - **Add a CLAUDE.md** - This is the single most impactful thing you can do. The agent loads project configuration from `CLAUDE.md`, `.claude/rules/*.md`, `.claude/settings.json`, and `.mcp.json` in your repository. Use these to document build commands, coding conventions, architecture decisions, and constraints. A good `CLAUDE.md` prevents the agent from guessing and reduces wasted turns. See the [Prompt guide](./PROMPT_GUIDE.md#repo-level-instructions) for examples. -- **Keep your PAT aligned** - If tasks fail with `preflight_failed`, the GitHub PAT likely lacks the permissions the task type needs. Check the event's `reason` field and update the secret in Secrets Manager. A task that fails with `Token cannot push to ` passed that check, but GitHub refused the token a push when the agent tested it right after cloning, before any work was done: the error names the token type and the permission to add. See [Repository preparation](./DEVELOPER_GUIDE.md#repository-preparation) for the full permissions table. +- **Keep your PAT aligned** - If tasks fail with `preflight_failed`, the GitHub PAT likely lacks the permissions the task type needs. Check the event's `reason` field and update the secret in Secrets Manager. A task whose error starts `PushCapabilityError:` (not `Pre-flight check failed:`) passed that check, but GitHub refused the token a push when the agent tested it right after cloning, before any work was done: the error names the cause and the fix, such as the token type and the permission to add. See [Repository preparation](./DEVELOPER_GUIDE.md#repository-preparation) for the full permissions table. ### Write effective task descriptions diff --git a/docs/src/content/docs/architecture/Security.md b/docs/src/content/docs/architecture/Security.md index 142565c1c..11aae361e 100644 --- a/docs/src/content/docs/architecture/Security.md +++ b/docs/src/content/docs/architecture/Security.md @@ -156,8 +156,8 @@ flowchart LR | Admission | Concurrency limit | `orchestrator.ts` | `admission_queued` event | | Pre-flight | GitHub access, PAT permissions, PR access | `preflight.ts` | `preflight_failed` event | | Hydration | Guardrail prompt screening | `context-hydration.ts` | `guardrail_blocked` event | -| Repo setup | GitHub token may push (dry-run push, skipped for read-only workflows) | `agent/src/repo.py` | `agent_blocked` event, task `FAILED` before the agent runs | | Hydration | Budget/quota resolution | `orchestrator.ts` | Persisted on task record | +| Repo setup | GitHub token may push (dry-run push, skipped for read-only workflows) | `agent/src/repo.py` | `agent_blocked` event, task `FAILED` before the agent runs | | Execution | Tool-call policy (Cedar) | `agent/src/hooks.py`, `agent/src/policy.py` | `POLICY_DECISION` telemetry | | Execution | Output secret screening | `agent/src/output_scanner.py` | `OUTPUT_SCREENING` telemetry | | Execution | Turn/cost budget | Claude Agent SDK | Cost in task result | diff --git a/docs/src/content/docs/using/Tips-for-being-a-good-citizen.md b/docs/src/content/docs/using/Tips-for-being-a-good-citizen.md index bbdd2bf45..7ae1f777e 100644 --- a/docs/src/content/docs/using/Tips-for-being-a-good-citizen.md +++ b/docs/src/content/docs/using/Tips-for-being-a-good-citizen.md @@ -10,7 +10,7 @@ The agent is only as good as the context it receives. A well-prepared repository - **Onboard first** - Repositories must be registered via a Blueprint construct before tasks can target them. If you get a `REPO_NOT_ONBOARDED` error, contact your platform administrator. - **Add a CLAUDE.md** - This is the single most impactful thing you can do. The agent loads project configuration from `CLAUDE.md`, `.claude/rules/*.md`, `.claude/settings.json`, and `.mcp.json` in your repository. Use these to document build commands, coding conventions, architecture decisions, and constraints. A good `CLAUDE.md` prevents the agent from guessing and reduces wasted turns. See the [Prompt guide](/sample-autonomous-cloud-coding-agents/customizing/prompt-engineering#repo-level-instructions) for examples. -- **Keep your PAT aligned** - If tasks fail with `preflight_failed`, the GitHub PAT likely lacks the permissions the task type needs. Check the event's `reason` field and update the secret in Secrets Manager. A task that fails with `Token cannot push to ` passed that check, but GitHub refused the token a push when the agent tested it right after cloning, before any work was done: the error names the token type and the permission to add. See [Repository preparation](/sample-autonomous-cloud-coding-agents/developer-guide/repository-preparation) for the full permissions table. +- **Keep your PAT aligned** - If tasks fail with `preflight_failed`, the GitHub PAT likely lacks the permissions the task type needs. Check the event's `reason` field and update the secret in Secrets Manager. A task whose error starts `PushCapabilityError:` (not `Pre-flight check failed:`) passed that check, but GitHub refused the token a push when the agent tested it right after cloning, before any work was done: the error names the cause and the fix, such as the token type and the permission to add. See [Repository preparation](/sample-autonomous-cloud-coding-agents/developer-guide/repository-preparation) for the full permissions table. ### Write effective task descriptions diff --git a/osv-scanner.toml b/osv-scanner.toml index 2b6b86dde..0dfd96a6f 100644 --- a/osv-scanner.toml +++ b/osv-scanner.toml @@ -5,7 +5,7 @@ [[IgnoredVulns]] id = "GHSA-fc5q-39xc-vjpf" ignoreUntil = 2026-12-16 -reason = "picomatch regular-expression denial of service on a crafted glob pattern (every release through 4.0.7, the latest; the advisory was updated on 2026-11-17, and on 2026-11-18 no fixed release exists). The locked copies, 2.3.2, 4.0.5 and 4.0.7, belong to build, test and lint tooling only (jest, vitest, vite, astro, knip, typescript-eslint, the ESLint stylistic plugin, the docs link validator); no runtime dependency of cdk, cli or web reaches picomatch, so no Lambda bundle, the CLI or the console ships it. They match only patterns from this repository's own configuration, never a pattern from a request. #1052 accepts the same advisory." +reason = "picomatch regular-expression denial of service on a crafted glob pattern (every release through 4.0.7, the latest; the advisory was updated on 2026-11-17, and on 2026-11-18 no fixed release exists). The locked copies, 2.3.2, 4.0.5 and 4.0.7, belong to build, test and lint tooling only (jest, vitest, vite, astro, knip, typescript-eslint, the ESLint stylistic plugin, the docs link validator); no runtime dependency of cdk, cli or web reaches picomatch, so no Lambda bundle, the CLI or the console ships it. The docs site lists it among its production dependencies (through astro), but builds to static files that ship no matcher. They match only patterns from this repository's own configuration, never a pattern from a request. This entry covers yarn.lock only: the agent image's global claude-code npm tree carries its own copy (agent/Dockerfile updates it with npm update), which the image scan (trivy --ignore-unfixed) will report once a fixed release exists. #1052 accepts the same advisory." [[IgnoredVulns]] id = "GHSA-g3hv-75wg-m249" From 2ac5526d170ddc59ad718a5982027242f8e07ba6 Mon Sep 17 00:00:00 2001 From: bgagent Date: Wed, 18 Nov 2026 18:22:12 -0600 Subject: [PATCH 5/6] fix(agent): check the task's own token, skip artifact tasks, name the 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. --- agent/README.md | 8 +- agent/src/pipeline.py | 8 +- agent/src/repo.py | 78 +++++++++--- agent/src/workflow/models.py | 13 ++ agent/tests/test_repo.py | 115 +++++++++++++++++- cdk/src/handlers/shared/error-classifier.ts | 29 +++++ .../handlers/shared/error-classifier.test.ts | 45 ++++++- osv-scanner.toml | 5 - 8 files changed, 265 insertions(+), 36 deletions(-) diff --git a/agent/README.md b/agent/README.md index bc73bf851..f469cee53 100644 --- a/agent/README.md +++ b/agent/README.md @@ -40,9 +40,11 @@ Go to GitHub > **Settings** > **Developer settings** > **Personal access tokens* | Scope | Reason | |-------|--------| -| `repo` | Full repository access (clone, push, PRs, issues) | +| `public_repo` (public repositories) or `repo` (private repositories) | Clone, push, PRs and issues. `public_repo` reaches public repositories only; `repo` grants every private repository the token's owner can reach, so use it only when a target repository is private | | `read:org` | Resolve org membership for org-owned repos | +A token acts for its owner: whatever the scopes, the owner needs write access to the repository (collaborator or team role) for the agent to push. + Set an expiration (90 days recommended) and store it in Secrets Manager the same way as a fine-grained token. #### When to use which @@ -66,7 +68,9 @@ A token can read a repository and still be refused every push. A classic PAT wit | The organization enforces SAML single sign-on, or an IP allow list | `GitHub organization policy blocks pushes to `, naming the policy and its fix | | No answer: GitHub or the network down after retries, or no reply within 120 s | `BLOCKED[dependency_unreachable]`, retryable | -The dry run sends no ref update, so the remote is not changed. It checks write access only: branch rules and push protection are evaluated on a real push. Read-only workflows (`coding/pr-review-v1`) never push and skip the check. +The dry run sends no ref update, so the remote is not changed. It checks write access only: branch rules and push protection are evaluated on a real push. Tasks that never push skip the check: read-only workflows (`coding/pr-review-v1`) and repository-bound workflows that deliver an artifact instead of a PR. + +Setup clears the credential helpers the clone would inherit from the machine's git configuration (a saved GitHub login, for instance) before adding `gh`, so the check and the final push use the task's token, never another credential. ### AWS Credentials diff --git a/agent/src/pipeline.py b/agent/src/pipeline.py index bc76f1a10..050add726 100644 --- a/agent/src/pipeline.py +++ b/agent/src/pipeline.py @@ -1368,11 +1368,9 @@ def _on_trace_truncated(max_bytes: int, first_dropped: int) -> None: # takes THIS path yet still expects a PR (primary: artifact but # requires_repo: false). So gate on requires_repo too, or a # repo-optional default-agent run would wrongly skip its PR. - artifact_workflow = bool( - _workflow - and getattr(_workflow.terminal_outcomes, "primary", None) == "artifact" - and getattr(_workflow, "requires_repo", False) - ) + # The rule is Workflow.delivers_repo_artifact, which the push preflight in + # repo.setup_repo applies too, so a task it skips is one that never pushes. + artifact_workflow = bool(_workflow and _workflow.delivers_repo_artifact) artifact_uri: str | None = None # set by the artifact branch below # Clarify-before-spend (UX #4): a writeable, PR-producing task diff --git a/agent/src/repo.py b/agent/src/repo.py index 0a50bc9f0..7e5a129a0 100644 --- a/agent/src/repo.py +++ b/agent/src/repo.py @@ -237,15 +237,21 @@ def _token_remedy(token: str, repo_url: str) -> _TokenRemedy: """The token type and the permission to add, for a token GitHub refused a push. Reads only the documented type prefix of the token; the token itself never - reaches the message.""" + reaches the message. A personal access token acts for its owner, so the owner + needs write access to the repository as well: the remedies say so.""" + owner = f"its owner needs write access to {repo_url}" + classic = ( + f"give the token the `public_repo` scope if {repo_url} is public, or `repo` if " + "it is private (`repo` grants every private repository its owner can reach)" + ) + fine_grained = ( + f"include {repo_url} in the token's repository access and give it the Contents " + "permission with Read and write access" + ) if token.startswith("github_pat_"): - return _TokenRemedy( - "fine-grained personal access token", - f"include {repo_url} in the token's repository access and give it the " - "Contents permission with Read and write access", - ) + return _TokenRemedy("fine-grained personal access token", f"{fine_grained}; {owner}") if token.startswith("ghp_"): - return _TokenRemedy("classic personal access token", "give the token the `repo` scope") + return _TokenRemedy("classic personal access token", f"{classic}; {owner}") if token.startswith(("ghs_", "ghu_")): return _TokenRemedy( "GitHub App token", @@ -254,9 +260,8 @@ def _token_remedy(token: str, repo_url: str) -> _TokenRemedy: ) return _TokenRemedy( "GitHub token", - f"use a fine-grained personal access token with access to {repo_url} and the " - "Contents permission with Read and write access, or a classic one with the " - "`repo` scope", + f"for a fine-grained personal access token, {fine_grained}; for a classic one, " + f"{classic}; either way, {owner}", ) @@ -406,6 +411,48 @@ def _report_refusal(refusal: PushCapabilityError, config: TaskConfig, progress: ) +def _configure_git_credentials(repo_dir: str) -> None: + """Make the task's token the only credential git uses for this clone. + + Git asks every configured credential helper in turn (system, global, then + local config) and takes the first credential one returns. On a developer + machine a saved GitHub login (osxkeychain, a credential store, a global ``gh`` + helper) would answer before a helper added here, so the push preflight, and the + final push, would run as that login instead of the task's token. An empty + ``credential.helper`` in the local config clears every helper read before it, + URL-scoped ones included, so only ``gh``, reading ``GH_TOKEN``/``GITHUB_TOKEN``, + answers.""" + run_cmd( + ["git", "config", "--local", "credential.helper", ""], + label="reset-git-credential-helpers", + cwd=repo_dir, + ) + run_cmd( + ["git", "config", "--local", "--add", "credential.helper", "!gh auth git-credential"], + label="configure-git-credential-helper", + cwd=repo_dir, + ) + + +def _task_pushes(config: TaskConfig) -> bool: + """Whether the task's post-hooks will push, by the rules they apply. + + Read-only workflows never push. A repository-bound workflow whose primary + outcome is an artifact clones for context and delivers a document instead of a + PR (``Workflow.delivers_repo_artifact``, the rule the pipeline's post-hooks + use). When the workflow cannot be loaded the post-hooks fall back to opening a + PR, which pushes, so the check runs.""" + if config.read_only: + return False + from workflow import WorkflowValidationError, load_workflow + + try: + workflow = load_workflow((config.resolved_workflow or {}).get("id", "coding/new-task-v1")) + except WorkflowValidationError: + return True + return not workflow.delivers_repo_artifact + + def _preflight_push_capability(config: TaskConfig, repo_dir: str, progress: Any) -> None: """Fail the task now if GitHub refuses the token a push to the repository (#801). @@ -426,10 +473,11 @@ def _preflight_push_capability(config: TaskConfig, repo_dir: str, progress: Any) on the command line. The check covers write access only: branch rules and push protection are evaluated on a real push, which a dry run never makes. - Read-only workflows are not checked: they never push, and a token that may not + Tasks that never push are not checked (``_task_pushes``): read-only workflows, + and repository-bound workflows that deliver an artifact. A token that may not write is fit for them. """ - if config.read_only: + if not _task_pushes(config): return log("SETUP", f"Checking that the GitHub token can push to {config.repo_url}...") @@ -593,11 +641,7 @@ def setup_repo(config: TaskConfig, progress: Any = None) -> RepoSetup: # noqa: label="set-remote-url", cwd=repo_dir, ) - run_cmd( - ["git", "config", "--local", "credential.helper", "!gh auth git-credential"], - label="configure-git-credential-helper", - cwd=repo_dir, - ) + _configure_git_credentials(repo_dir) # Fail in seconds, not after the agent's whole run, on a token that may not push. _preflight_push_capability(config, repo_dir, progress) diff --git a/agent/src/workflow/models.py b/agent/src/workflow/models.py index 5a91003c2..11e1277d0 100644 --- a/agent/src/workflow/models.py +++ b/agent/src/workflow/models.py @@ -239,3 +239,16 @@ def resolved_requires_repo(self) -> bool: if self.requires_repo is not None: return self.requires_repo return self.domain == "coding" + + @property + def delivers_repo_artifact(self) -> bool: + """A repository-bound workflow whose terminal outcome is a document, not a PR. + + It clones the repository for context, skips the build and PR post-hooks and + delivers the agent's result as an artifact, so it never pushes. Both + conditions matter: ``default/agent-v1`` declares ``primary: artifact`` but + ``requires_repo: false``, and run with a repository it still opens a PR. + Reads the declared ``requires_repo``, not ``resolved_requires_repo``: a + workflow must opt in to artifact delivery explicitly. + """ + return self.terminal_outcomes.primary == "artifact" and bool(self.requires_repo) diff --git a/agent/tests/test_repo.py b/agent/tests/test_repo.py index a3c6abd46..8b493b2ba 100644 --- a/agent/tests/test_repo.py +++ b/agent/tests/test_repo.py @@ -5,6 +5,7 @@ (detect_default_branch) — recording argv and returning scripted results. """ +import os import subprocess from types import SimpleNamespace @@ -73,10 +74,15 @@ def test_new_task_argv_sequence_and_remote_url_has_no_token(self, monkeypatch): assert "x-access-token" not in remote assert "ghp_" not in " ".join(set_url_cmd) - # And the credential.helper config call is present (token resolved at call time). + # And the credential.helper config call is present (token resolved at call time), + # after a reset of every inherited helper (#801 review). helper_cmd = fake.cmd_for("configure-git-credential-helper") assert helper_cmd is not None assert "credential.helper" in helper_cmd + assert fake.cmd_for("reset-git-credential-helpers")[-2:] == ["credential.helper", ""] + assert labels.index("reset-git-credential-helpers") < labels.index( + "configure-git-credential-helper" + ) # Derived branch slug for a new task. assert setup.branch.startswith("bgagent/task-abc/") @@ -985,6 +991,60 @@ def test_read_only_matches_the_coding_workflows_that_never_push(self): for pushing in ("coding/new-task-v1", "coding/pr-iteration-v1", "coding/restack-v1"): assert load_workflow(pushing).read_only is False, pushing + def _artifact_workflow(self): + # The real coding workflow with only the two fields that make it deliver a + # document, as the pipeline's artifact test builds it. + from workflow import load_workflow + + base = load_workflow("coding/new-task-v1") + return base.model_copy( + update={ + "id": "synthetic/artifact-repoful-v1", + "requires_repo": True, + "terminal_outcomes": base.terminal_outcomes.model_copy( + update={"primary": "artifact"} + ), + } + ) + + def test_repo_bound_artifact_workflow_is_not_gated(self, monkeypatch): + # It clones for context and delivers a document to S3; it never pushes, so + # a token that may only read is fit for it (#801 review). + artifact_wf = self._artifact_workflow() + assert artifact_wf.delivers_repo_artifact + fake = _PreflightFake(preflight_rc=128, preflight_stderr=_DENIED_403) + self._setup(monkeypatch, fake) + monkeypatch.setattr("workflow.load_workflow", lambda workflow_id: artifact_wf) + + repo.setup_repo( + _config(resolved_workflow={"id": "synthetic/artifact-repoful-v1", "version": "1"}) + ) + + assert "push-preflight" not in fake.labels() + assert "create-branch" in fake.labels() + + def test_repo_optional_artifact_workflow_with_a_repo_is_gated(self, monkeypatch): + # default/agent-v1 declares primary: artifact but requires_repo: false; run + # with a repository it still opens a PR, so it is checked. + from workflow import load_workflow + + assert not load_workflow("default/agent-v1").delivers_repo_artifact + self._raises( + monkeypatch, + _DENIED_403, + resolved_workflow={"id": "default/agent-v1", "version": "1.0.0"}, + ) + + def test_unloadable_workflow_is_gated(self, monkeypatch): + # The post-hooks then fall back to opening a PR, which pushes. + from workflow import WorkflowValidationError + + def _broken(workflow_id): + raise WorkflowValidationError("bad file") + + monkeypatch.setattr("workflow.load_workflow", _broken) + self._raises(monkeypatch, _DENIED_403, resolved_workflow={"id": "x/y-v1", "version": "1"}) + def test_fine_grained_token_passes_on_the_servers_verdict(self, monkeypatch): # GitHub returns no X-OAuth-Scopes header for a fine-grained PAT; the dry # run reads no scopes, so it passes on the server's verdict alone. @@ -1011,7 +1071,10 @@ def test_classic_token_without_scopes_fails_before_the_agent_runs(self, monkeypa # scopes" (cdk/src/handlers/shared/error-classifier.ts). assert message.startswith("Token cannot push to owner/repo") assert "classic personal access token" in message - assert "`repo` scope" in message + # Both cases: public_repo is enough for a public repository, and repo, which + # also grants every private repository, only for a private one. + assert "`public_repo` scope if owner/repo is public, or `repo` if it is private" in message + assert "its owner needs write access to owner/repo" in message assert "Repository not found" in message assert "agent/README.md" in message assert token not in message @@ -1040,7 +1103,7 @@ def test_unknown_token_type_gets_both_remedies(self, monkeypatch): _, message = self._raises(monkeypatch, _DENIED_403, github_token="") assert "Contents permission" in message - assert "`repo` scope" in message + assert "`public_repo` scope" in message def test_github_app_token_remedy(self): remedy = repo._token_remedy("ghs_" + "e" * 36, "owner/repo") @@ -1063,7 +1126,7 @@ def test_archived_repository_is_not_blamed_on_the_token(self, monkeypatch): assert message.startswith("Repository owner/repo is archived on GitHub, so it is read-only") assert "Token cannot push" not in message - assert "`repo` scope" not in message + assert "`public_repo`" not in message def test_saml_enforcement_names_sso_authorization(self, monkeypatch): _, message = self._raises(monkeypatch, _SAML, github_token="ghp_" + "b" * 36) @@ -1071,7 +1134,7 @@ def test_saml_enforcement_names_sso_authorization(self, monkeypatch): assert message.startswith("GitHub organization policy blocks pushes to owner/repo") assert "SAML single sign-on" in message assert "Configure SSO" in message - assert "`repo` scope" not in message + assert "`public_repo`" not in message def test_ip_allow_list_names_the_allow_list(self, monkeypatch): _, message = self._raises(monkeypatch, _IP_ALLOW_LIST) @@ -1097,7 +1160,7 @@ def test_names_never_pick_the_cause(self, monkeypatch): github_token="ghp_" + "b" * 36, ) assert message.startswith(f"Token cannot push to {repo_url}"), repo_url - assert "`repo` scope" in message + assert "`public_repo` scope" in message assert "SAML" not in message assert "is archived on GitHub" not in message @@ -1380,3 +1443,43 @@ def test_pre_push_hook_does_not_run(self, tmp_path, monkeypatch): repo._preflight_push_capability(_config(), str(work), progress=None) assert not marker.exists() + + def test_only_the_tasks_token_answers_for_github(self, tmp_path, monkeypatch): + # A developer machine can have a saved GitHub login (a global helper, also a + # URL-scoped one). Git asks helpers in order and takes the first answer, so + # without the reset it would answer instead of the task's token (#801 review). + _, work = self._remote_and_clone(tmp_path, monkeypatch) + bin_dir = tmp_path / "bin" + bin_dir.mkdir() + # Stand-ins for gh and for a saved login; the real gh is never called. + (bin_dir / "gh").write_text( + "#!/bin/sh\ncat >/dev/null\necho username=task-token\necho password=x\n" + ) + marker = tmp_path / "saved-login-asked" + (bin_dir / "saved-login").write_text( + f"#!/bin/sh\ncat >/dev/null\ntouch {marker}\n" + "echo username=saved-login\necho password=y\n" + ) + for f in bin_dir.iterdir(): + f.chmod(0o755) + global_cfg = tmp_path / "global.gitconfig" + global_cfg.write_text( + f"[credential]\n\thelper = !{bin_dir}/saved-login\n" + f'[credential "https://github.com"]\n\thelper = !{bin_dir}/saved-login\n' + ) + monkeypatch.setenv("GIT_CONFIG_GLOBAL", str(global_cfg)) + monkeypatch.setenv("PATH", f"{bin_dir}{os.pathsep}{os.environ['PATH']}") + + repo._configure_git_credentials(str(work)) + + filled = subprocess.run( + ["git", "credential", "fill"], + cwd=work, + input="protocol=https\nhost=github.com\npath=owner/repo.git\n\n", + capture_output=True, + text=True, + check=True, + env={**os.environ, "GIT_TERMINAL_PROMPT": "0"}, + ).stdout + assert "username=task-token" in filled + assert not marker.exists() diff --git a/cdk/src/handlers/shared/error-classifier.ts b/cdk/src/handlers/shared/error-classifier.ts index 730ffaf1a..09d1fab0b 100644 --- a/cdk/src/handlers/shared/error-classifier.ts +++ b/cdk/src/handlers/shared/error-classifier.ts @@ -747,6 +747,30 @@ const PATTERNS: readonly ErrorPattern[] = [ ]; +/** + * The agent's push preflight refusal (``PushCapabilityError`` in agent/src/repo.py): + * ``Token cannot push to : GitHub refused the write access (). To fix it, . The task stopped before the agent ran …``. The fix + * depends on the token type (scope for a classic PAT, repository access and + * Contents for a fine-grained one, installation for a GitHub App), so the + * classification carries the agent's own fix rather than the generic remedy of + * the ``Token cannot push`` pattern, which the orchestrator's preflight shares. + * The fix is matched up to the sentence that follows it, so a period inside it (a + * repository named ``a.b``) does not cut it short. + */ +const AGENT_PUSH_REFUSAL = /Token cannot push to (\S+): GitHub refused the (.+?) write access \(.*?\)\. To fix it, (.+?)\. The task stopped before the agent ran/; + +function agentPushRefusalClassification(repo: string, tokenType: string, fix: string): ErrorClassification { + return { + category: ErrorCategory.AUTH, + title: 'Insufficient GitHub token scopes', + description: `GitHub refused the ${tokenType} write access to ${repo}.`, + remedy: `${fix.charAt(0).toUpperCase()}${fix.slice(1)}. Then resubmit. The permissions each token type needs are in agent/README.md, GitHub PAT — Minimal Permissions.`, + retryable: false, + errorClass: ErrorClass.SERVICE, + }; +} + /** * Canonical blocker-reason contract. Matches ``BLOCKED[]`` and, * separately, the optional `` (resource: )`` @@ -901,6 +925,11 @@ export function classifyError(errorMessage: string | undefined | null): ErrorCla return blockerClassification(kindMatch[1].toLowerCase(), resource); } + const pushRefusal = AGENT_PUSH_REFUSAL.exec(errorMessage); + if (pushRefusal) { + return agentPushRefusalClassification(pushRefusal[1], pushRefusal[2], pushRefusal[3]); + } + for (const { pattern, exclude, classification } of PATTERNS) { if (pattern.test(errorMessage) && (!exclude || !exclude.test(errorMessage))) { return classification; diff --git a/cdk/test/handlers/shared/error-classifier.test.ts b/cdk/test/handlers/shared/error-classifier.test.ts index 9459e21ec..e371174d8 100644 --- a/cdk/test/handlers/shared/error-classifier.test.ts +++ b/cdk/test/handlers/shared/error-classifier.test.ts @@ -21,6 +21,13 @@ import { classifyError, ErrorCategory, ErrorClass, isTransientError, retryGuidan import { LAMBDA_MICROVM_SUPPORTED_REGIONS } from '../../../src/handlers/shared/microvm-regions'; import { toTaskDetail, type TaskRecord } from '../../../src/handlers/shared/types'; +// Persisted agent push preflight refusals, printed from agent/src/repo.py. +const MSG_CLASSIC = 'PushCapabilityError: Token cannot push to owner/repo: GitHub refused the classic personal access token write access (remote: Permission to owner/repo.git denied to ). To fix it, give the token the `public_repo` scope if owner/repo is public, or `repo` if it is private (`repo` grants every private repository its owner can reach); its owner needs write access to owner/repo. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; +const MSG_FINE = 'PushCapabilityError: Token cannot push to owner/repo: GitHub refused the fine-grained personal access token write access (remote: Permission to owner/repo.git denied to ). To fix it, include owner/repo in the token\'s repository access and give it the Contents permission with Read and write access; its owner needs write access to owner/repo. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; +const MSG_APP = 'PushCapabilityError: Token cannot push to owner/repo: GitHub refused the GitHub App token write access (remote: Permission to owner/repo.git denied to ). To fix it, give the app the Contents permission with Read and write access and install it on owner/repo. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; +const MSG_UNKNOWN = 'PushCapabilityError: Token cannot push to owner/repo: GitHub refused the GitHub token write access (remote: Permission to owner/repo.git denied to ). To fix it, for a fine-grained personal access token, include owner/repo in the token\'s repository access and give it the Contents permission with Read and write access; for a classic one, give the token the `public_repo` scope if owner/repo is public, or `repo` if it is private (`repo` grants every private repository its owner can reach); either way, its owner needs write access to owner/repo. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; +const MSG_DOTTED = 'PushCapabilityError: Token cannot push to owner/my.repo: GitHub refused the classic personal access token write access (remote: Permission to owner/my.repo.git denied to ). To fix it, give the token the `public_repo` scope if owner/my.repo is public, or `repo` if it is private (`repo` grants every private repository its owner can reach); its owner needs write access to owner/my.repo. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; + describe('classifyError', () => { // --- Null / empty inputs --- @@ -94,7 +101,7 @@ describe('classifyError', () => { test.each([ [ 'a token without write access', - 'PushCapabilityError: Token cannot push to owner/repo: GitHub refused the classic personal access token write access (remote: Permission to owner/repo.git denied to ). To fix it, give the token the `repo` scope. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.', + MSG_CLASSIC, ErrorCategory.AUTH, 'Insufficient GitHub token scopes', ], @@ -131,6 +138,33 @@ describe('classifyError', () => { expect(result!.retryable).toBe(false); }); + // The refusal's fix depends on the token type. The classification (which the + // web console's failure banner shows) carries the agent's fix, not the generic + // fine-grained-PAT remedy of the orchestrator's message (#801 review). + test.each([ + ['a classic PAT', MSG_CLASSIC, 'owner/repo', ['`public_repo` scope if owner/repo is public', '`repo` if it is private', 'its owner needs write access']], + ['a fine-grained PAT', MSG_FINE, 'owner/repo', ['repository access', 'Contents permission with Read and write access']], + ['a GitHub App token', MSG_APP, 'owner/repo', ['install it on owner/repo']], + ['an unknown token type', MSG_UNKNOWN, 'owner/repo', ['For a fine-grained personal access token', 'for a classic one']], + ['a repository with a dot in its name', MSG_DOTTED, 'owner/my.repo', ['its owner needs write access to owner/my.repo']], + ])('carries the agent push preflight fix for %s (#801)', (_label, message, repo, fragments) => { + const result = classifyError(message); + expect(result!.title).toBe('Insufficient GitHub token scopes'); + expect(result!.description).toContain(repo); + for (const fragment of fragments) { + expect(result!.remedy).toContain(fragment); + } + expect(result!.remedy).toMatch(/Then resubmit\.$|Then resubmit\. /); + // Not the orchestrator pattern's generic remedy. + expect(result!.remedy).not.toContain('Update the PAT with'); + expect(result!.retryable).toBe(false); + }); + + test('keeps the generic remedy for the orchestrator preflight message', () => { + const result = classifyError('Pre-flight check failed: INSUFFICIENT_GITHUB_REPO_PERMISSIONS — Token cannot push to owner/repo. Required: push.'); + expect(result!.title).toBe('Insufficient GitHub permissions'); + }); + test('classifies bare "Token cannot interact with pull requests on" without error code', () => { const result = classifyError('Token cannot interact with pull requests on owner/repo'); expect(result!.category).toBe(ErrorCategory.AUTH); @@ -1062,6 +1096,15 @@ describe('classifyError', () => { expect(detail.error_classification!.title).toBe('Concurrency limit reached'); }); + test('gives the console the token-specific fix of an agent push preflight refusal (#801)', () => { + // web/src/core/util/progress.ts shows `${description} What to do: ${remedy}`. + const detail = toTaskDetail({ ...baseRecord, error_message: MSG_APP }); + expect(detail.error_classification!.description).toContain('GitHub App token'); + expect(detail.error_classification!.remedy).toContain('install it on owner/repo'); + expect(detail.error_classification!.remedy).not.toContain('fine-grained'); + expect(detail.error_classification!.remedy).not.toContain('Update the PAT'); + }); + test('returns null error_classification when error_message is undefined', () => { const detail = toTaskDetail(baseRecord); expect(detail.error_message).toBeNull(); diff --git a/osv-scanner.toml b/osv-scanner.toml index 0dfd96a6f..cd7490131 100644 --- a/osv-scanner.toml +++ b/osv-scanner.toml @@ -2,11 +2,6 @@ # lockfiles in this directory. Each entry expires so the scan fails again and the # finding is re-reviewed; remove an entry as soon as a fixed release is available. -[[IgnoredVulns]] -id = "GHSA-fc5q-39xc-vjpf" -ignoreUntil = 2026-12-16 -reason = "picomatch regular-expression denial of service on a crafted glob pattern (every release through 4.0.7, the latest; the advisory was updated on 2026-11-17, and on 2026-11-18 no fixed release exists). The locked copies, 2.3.2, 4.0.5 and 4.0.7, belong to build, test and lint tooling only (jest, vitest, vite, astro, knip, typescript-eslint, the ESLint stylistic plugin, the docs link validator); no runtime dependency of cdk, cli or web reaches picomatch, so no Lambda bundle, the CLI or the console ships it. The docs site lists it among its production dependencies (through astro), but builds to static files that ship no matcher. They match only patterns from this repository's own configuration, never a pattern from a request. This entry covers yarn.lock only: the agent image's global claude-code npm tree carries its own copy (agent/Dockerfile updates it with npm update), which the image scan (trivy --ignore-unfixed) will report once a fixed release exists. #1052 accepts the same advisory." - [[IgnoredVulns]] id = "GHSA-g3hv-75wg-m249" ignoreUntil = 2026-12-16 From 8b33dbc81a1d099129d8b70a9b65168dd9dfaf1c Mon Sep 17 00:00:00 2001 From: bgagent Date: Fri, 20 Nov 2026 11:21:41 -0600 Subject: [PATCH 6/6] fix(agent): pin the push URL, scope the credential reset, follow the PR strategy (#801) From krokoko's second review of #1053: - A url..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. --- agent/README.md | 2 +- agent/src/pipeline.py | 6 +- agent/src/repo.py | 96 ++++--- agent/src/workflow/models.py | 12 + agent/tests/test_repo.py | 234 ++++++++++++++++-- .../handlers/shared/error-classifier.test.ts | 23 +- 6 files changed, 310 insertions(+), 63 deletions(-) diff --git a/agent/README.md b/agent/README.md index ec13c78d3..eeb2ac578 100644 --- a/agent/README.md +++ b/agent/README.md @@ -70,7 +70,7 @@ A token can read a repository and still be refused every push. A classic PAT wit The dry run sends no ref update, so the remote is not changed. It checks write access only: branch rules and push protection are evaluated on a real push. Tasks that never push skip the check: read-only workflows (`coding/pr-review-v1`) and repository-bound workflows that deliver an artifact instead of a PR. -Setup clears the credential helpers the clone would inherit from the machine's git configuration (a saved GitHub login, for instance) before adding `gh`, so the check and the final push use the task's token, never another credential. +Setup also makes every push from the clone use the task's token over HTTPS. It pins the push URL to `https://github.com//.git`, which git's `pushInsteadOf` rules do not rewrite, and stops with an error if an `insteadOf` rule in the machine's git configuration still would. It clears the `github.com` credential helpers the clone would inherit (a saved GitHub login, for instance) before adding `gh`; helpers for other hosts keep working. Tasks whose workflow only looks up an existing pull request (`ensure_pr` with the `resolve` strategy) skip the check, as they never push. ### AWS Credentials diff --git a/agent/src/pipeline.py b/agent/src/pipeline.py index e7ea62c26..78733c427 100644 --- a/agent/src/pipeline.py +++ b/agent/src/pipeline.py @@ -1507,10 +1507,8 @@ def _on_trace_truncated(max_bytes: int, first_dropped: int) -> None: _workflow = load_workflow( (config.resolved_workflow or {}).get("id", DEFAULT_WORKFLOW_ID) ) - ensure_pr_strategy = next( - (s.strategy for s in _workflow.steps if s.kind == "ensure_pr" and s.strategy), - "create", - ) + # The rule the push preflight in repo.setup_repo applies too. + ensure_pr_strategy = _workflow.ensure_pr_strategy except WorkflowValidationError as exc: log( "WARN", diff --git a/agent/src/repo.py b/agent/src/repo.py index 9bc869727..ca80a3710 100644 --- a/agent/src/repo.py +++ b/agent/src/repo.py @@ -117,7 +117,8 @@ def _fail_setup_command(label: str, resource: str, stderr: str, progress: Any) - # TaskResult.error (DynamoDB, `bgagent status`). The original check=True # path redacted here (shell.py run_cmd); preserve that so a credential in # git stderr never lands in cleartext. - snippet = redact_secrets((stderr or "").strip()[:500]) + # Redact first: a cut can remove the prefix the redactor recognizes a token by. + snippet = redact_secrets((stderr or "").strip())[:500] raise RuntimeError(f"{label} failed (non-transient): {snippet}") # (2) Transient with no nameable host. @@ -231,20 +232,23 @@ class _TokenRemedy(NamedTuple): remedy: str -def _token_remedy(token: str, repo_url: str) -> _TokenRemedy: +def _token_remedy(token: str) -> _TokenRemedy: """The token type and the permission to add, for a token GitHub refused a push. Reads only the documented type prefix of the token; the token itself never reaches the message. A personal access token acts for its owner, so the owner - needs write access to the repository as well: the remedies say so.""" - owner = f"its owner needs write access to {repo_url}" + needs write access to the repository as well: the remedies say so. They say + "the repository", never its name: the message names it once, and a long + ``owner/repo`` repeated in every remedy could push the end of the message past + what the task record stores, where the classifier reads it.""" + owner = "its owner needs write access to the repository" classic = ( - f"give the token the `public_repo` scope if {repo_url} is public, or `repo` if " - "it is private (`repo` grants every private repository its owner can reach)" + "give the token the `public_repo` scope for a public repository, or `repo` for a " + "private one (`repo` grants every private repository its owner can reach)" ) fine_grained = ( - f"include {repo_url} in the token's repository access and give it the Contents " - "permission with Read and write access" + "include the repository in the token's repository access and give it the " + "Contents permission with Read and write access" ) if token.startswith("github_pat_"): return _TokenRemedy("fine-grained personal access token", f"{fine_grained}; {owner}") @@ -253,8 +257,8 @@ def _token_remedy(token: str, repo_url: str) -> _TokenRemedy: if token.startswith(("ghs_", "ghu_")): return _TokenRemedy( "GitHub App token", - "give the app the Contents permission with Read and write access and " - f"install it on {repo_url}", + "give the app the Contents permission with Read and write access and install " + "it on the repository", ) return _TokenRemedy( "GitHub token", @@ -271,7 +275,8 @@ def _quoted_line(lines: list[str], signatures: tuple[str, ...]) -> str: line = next((ln for ln in lines if any(s in ln.lower() for s in signatures)), "") line = re.sub(r"(?i)(denied to )\S+", r"\1", line or (lines[0] if lines else "")) - return redact_secrets(line[:200]) + # Redact first: a cut can remove the prefix the redactor recognizes a token by. + return redact_secrets(line)[:200] def _push_refusal(config: TaskConfig, stderr: str) -> PushCapabilityError | None: @@ -315,7 +320,7 @@ def _push_refusal(config: TaskConfig, stderr: str) -> PushCapabilityError | None cause="credential_rejected", ) if any(sig in low for sig in _PUSH_REFUSED_SIGNATURES): - token_type, remedy = _token_remedy(config.github_token, repo_url) + token_type, remedy = _token_remedy(config.github_token) return PushCapabilityError( f"Token cannot push to {repo_url}: GitHub refused the {token_type} write " f"access ({_quoted_line(lines, _PUSH_REFUSED_SIGNATURES)}). To fix it, " @@ -372,7 +377,8 @@ def _fail_push_preflight_timeout( output = exc.stderr.decode(errors="replace") if isinstance(exc.stderr, bytes) else exc.stderr if output: - log("WARN", f"push-preflight output before the timeout: {redact_secrets(output[-500:])}") + # Redact first: a cut can remove the prefix the redactor recognizes a token by. + log("WARN", f"push-preflight output before the timeout: {redact_secrets(output)[-500:]}") detail = f"push-preflight got no answer from GitHub within {_PUSH_PREFLIGHT_TIMEOUT_S}s" _record_blocker_reason("dependency_unreachable", detail, config.repo_url) if progress is not None: @@ -409,24 +415,54 @@ def _report_refusal(refusal: PushCapabilityError, config: TaskConfig, progress: ) -def _configure_git_credentials(repo_dir: str) -> None: - """Make the task's token the only credential git uses for this clone. +_GITHUB = "https://github.com" - Git asks every configured credential helper in turn (system, global, then - local config) and takes the first credential one returns. On a developer - machine a saved GitHub login (osxkeychain, a credential store, a global ``gh`` - helper) would answer before a helper added here, so the push preflight, and the - final push, would run as that login instead of the task's token. An empty - ``credential.helper`` in the local config clears every helper read before it, - URL-scoped ones included, so only ``gh``, reading ``GH_TOKEN``/``GITHUB_TOKEN``, - answers.""" + +def _configure_git_credentials(repo_dir: str, repo_url: str) -> None: + """Make every push from this clone go to GitHub over HTTPS with the task's token. + + - **The push URL.** A ``url..pushInsteadOf`` rule in the machine's git + config rewrites the push URL (to SSH, say) while the fetch URL stays HTTPS, so + the push preflight and the final push would use the developer's SSH key, not + the task's token. An explicit push URL is exempt from ``pushInsteadOf``. A plain + ``insteadOf`` rule rewrites it all the same, so the effective push URL is then + checked, and setup stops if it is not the HTTPS one. + - **The credential.** Git asks every credential helper that applies to a URL in + turn (system, global, then local config) and takes the first answer, so a + saved GitHub login would answer before a helper added here. An empty + ``credential.https://github.com.helper`` in the local config clears every + helper read before it for github.com, and only for github.com: a login for + another host keeps working. Then only ``gh`` answers there, reading + ``GH_TOKEN``/``GITHUB_TOKEN`` at call time; the token never touches disk. + """ + url = f"{_GITHUB}/{repo_url}.git" + run_cmd( + ["git", "remote", "set-url", "--push", "origin", url], + label="set-remote-push-url", + cwd=repo_dir, + ) + effective = run_cmd( + ["git", "remote", "get-url", "--push", "origin"], + label="get-remote-push-url", + cwd=repo_dir, + ).stdout.strip() + if effective != url: + from shell import redact_secrets + + raise RuntimeError( + f"git config rewrites the push URL of {repo_url} to {redact_secrets(effective)!r} " + "(a url..insteadOf rule in the system or global git config), so the push " + "would not use the task's GitHub token. Remove that rule, or run the agent " + "where git has no such configuration." + ) + helper_key = f"credential.{_GITHUB}.helper" run_cmd( - ["git", "config", "--local", "credential.helper", ""], + ["git", "config", "--local", helper_key, ""], label="reset-git-credential-helpers", cwd=repo_dir, ) run_cmd( - ["git", "config", "--local", "--add", "credential.helper", "!gh auth git-credential"], + ["git", "config", "--local", "--add", helper_key, "!gh auth git-credential"], label="configure-git-credential-helper", cwd=repo_dir, ) @@ -437,8 +473,10 @@ def _task_pushes(config: TaskConfig) -> bool: Read-only workflows never push. A repository-bound workflow whose primary outcome is an artifact clones for context and delivers a document instead of a - PR (``Workflow.delivers_repo_artifact``, the rule the pipeline's post-hooks - use). When the workflow cannot be loaded the post-hooks fall back to opening a + PR (``Workflow.delivers_repo_artifact``). A workflow whose ``ensure_pr`` step + uses the ``resolve`` strategy only looks up the existing PR + (``Workflow.ensure_pr_strategy``). Both are the rules the pipeline's post-hooks + use. When the workflow cannot be loaded the post-hooks fall back to opening a PR, which pushes, so the check runs.""" if config.read_only: return False @@ -448,7 +486,7 @@ def _task_pushes(config: TaskConfig) -> bool: workflow = load_workflow((config.resolved_workflow or {}).get("id", "coding/new-task-v1")) except WorkflowValidationError: return True - return not workflow.delivers_repo_artifact + return not (workflow.delivers_repo_artifact or workflow.ensure_pr_strategy == "resolve") def _preflight_push_capability(config: TaskConfig, repo_dir: str, progress: Any) -> None: @@ -706,7 +744,7 @@ def setup_repo(config: TaskConfig, progress: Any = None) -> RepoSetup: # noqa: label="set-remote-url", cwd=repo_dir, ) - _configure_git_credentials(repo_dir) + _configure_git_credentials(repo_dir, config.repo_url) # Fail in seconds, not after the agent's whole run, on a token that may not push. _preflight_push_capability(config, repo_dir, progress) diff --git a/agent/src/workflow/models.py b/agent/src/workflow/models.py index 7ff65e6c7..066ed12c9 100644 --- a/agent/src/workflow/models.py +++ b/agent/src/workflow/models.py @@ -243,6 +243,18 @@ def resolved_requires_repo(self) -> bool: return self.requires_repo return self.domain == "coding" + @property + def ensure_pr_strategy(self) -> EnsurePrStrategy: + """The strategy of the workflow's ``ensure_pr`` step: ``create`` when it has none. + + The pipeline's post-hooks and the push preflight in ``repo.setup_repo`` both + read it: ``resolve`` only looks up an existing PR, so it never pushes. + """ + return next( + (s.strategy for s in self.steps if s.kind == "ensure_pr" and s.strategy), + "create", + ) + @property def delivers_repo_artifact(self) -> bool: """A repository-bound workflow whose terminal outcome is a document, not a PR. diff --git a/agent/tests/test_repo.py b/agent/tests/test_repo.py index 1dd711a5a..804db27ba 100644 --- a/agent/tests/test_repo.py +++ b/agent/tests/test_repo.py @@ -31,9 +31,26 @@ def _fake_run_cmd( _config = make_task_config +def _answer_push_url(run): + """``run``, answering ``git remote get-url --push`` with the URL that + ``set-url --push`` set, as git does when no insteadOf rule rewrites it. Every + other command, and the query itself, still reach ``run``.""" + pushed: dict[str, str] = {} + + def wrapped(cmd, label, **kwargs): + if label == "set-remote-push-url": + pushed["url"] = cmd[-1] + result = run(cmd, label, **kwargs) + if label == "get-remote-push-url": + return SimpleNamespace(returncode=0, stdout=f"{pushed.get('url', '')}\n", stderr="") + return result + + return wrapped + + def _patch_common(monkeypatch, fake: FakeRunCmd): """Patch run_cmd everywhere repo.py reaches it, plus the commit-hook install.""" - monkeypatch.setattr(repo, "run_cmd", fake) + monkeypatch.setattr(repo, "run_cmd", _answer_push_url(fake)) # #251 Phase 2: clone/fetch now go through run_cmd_with_backoff. Route it to # the same fake so scripted returncodes drive both — the fake ignores the # extra retry kwargs (max_attempts/base_delay_s/on_retry/sleep) via **kwargs. @@ -113,14 +130,18 @@ def run(cmd, label, cwd=None, check=True, **_kwargs): elif label == "check-pr-fork": answer = "true\n" if from_fork else "false\n" return SimpleNamespace(returncode=0, stdout=answer, stderr="") - elif cmd[0] != "git" or label in ("safe-directory", "set-remote-url"): + elif cmd[0] != "git" or label in ( + "safe-directory", + "set-remote-url", + "set-remote-push-url", + ): return SimpleNamespace(returncode=0, stdout="", stderr="") elif offline and cmd[1] == "fetch": return SimpleNamespace(returncode=1, stdout="", stderr="fatal: connection reset") return shell.run_cmd(cmd, label, cwd=cwd, check=check) monkeypatch.setattr(repo, "AGENT_WORKSPACE", str(tmp_path / "workspace")) - monkeypatch.setattr(repo, "run_cmd", run) + monkeypatch.setattr(repo, "run_cmd", _answer_push_url(run)) monkeypatch.setattr(repo, "run_cmd_with_backoff", functools.partial(run, check=False)) monkeypatch.setattr(repo, "_install_commit_hook", lambda repo_dir: None) monkeypatch.setattr(repo, "detect_default_branch", lambda url, d: default) @@ -157,8 +178,11 @@ def test_new_task_argv_sequence_and_remote_url_has_no_token(self, monkeypatch): # after a reset of every inherited helper (#801 review). helper_cmd = fake.cmd_for("configure-git-credential-helper") assert helper_cmd is not None - assert "credential.helper" in helper_cmd - assert fake.cmd_for("reset-git-credential-helpers")[-2:] == ["credential.helper", ""] + assert "credential.https://github.com.helper" in helper_cmd + assert fake.cmd_for("reset-git-credential-helpers")[-2:] == [ + "credential.https://github.com.helper", + "", + ] assert labels.index("reset-git-credential-helpers") < labels.index( "configure-git-credential-helper" ) @@ -555,7 +579,7 @@ def test_baseline_build_uses_the_generous_verify_ceiling_not_600s(self, monkeypa from post_hooks import BUILD_VERIFY_TIMEOUT_S fake = self._RecordingFake() - monkeypatch.setattr(repo, "run_cmd", fake) + monkeypatch.setattr(repo, "run_cmd", _answer_push_url(fake)) monkeypatch.setattr(repo, "run_cmd_with_backoff", fake) monkeypatch.setattr(repo, "_install_commit_hook", lambda repo_dir: None) # The clone is faked here, so the real workspace never gets a @@ -577,7 +601,7 @@ def test_baseline_build_timeout_is_guarded_not_a_task_crash(self, monkeypatch): # (which crashed the task pre-agent); it degrades to "no baseline" and the # run proceeds with build_before=True (a timeout is not a regression). fake = self._RecordingFake(timeout_on="verify-build-pre") - monkeypatch.setattr(repo, "run_cmd", fake) + monkeypatch.setattr(repo, "run_cmd", _answer_push_url(fake)) monkeypatch.setattr(repo, "run_cmd_with_backoff", fake) monkeypatch.setattr(repo, "_install_commit_hook", lambda repo_dir: None) # The clone is faked here, so the real workspace never gets a @@ -596,7 +620,7 @@ def test_baseline_build_timeout_is_guarded_not_a_task_crash(self, monkeypatch): def test_baseline_lint_timeout_is_guarded(self, monkeypatch): fake = self._RecordingFake(timeout_on="verify-lint-pre") - monkeypatch.setattr(repo, "run_cmd", fake) + monkeypatch.setattr(repo, "run_cmd", _answer_push_url(fake)) monkeypatch.setattr(repo, "run_cmd_with_backoff", fake) monkeypatch.setattr(repo, "_install_commit_hook", lambda repo_dir: None) # The clone is faked here, so the real workspace never gets a @@ -622,7 +646,7 @@ def test_baseline_build_OOM_kill_is_not_a_regression(self, monkeypatch): # "red-before → red-after isn't the agent's fault → ✅" while the absolute # orchestration gate fails the node — a task GitHub built green. fake = self._RecordingFake(rc_on=("verify-build-pre", 137, "Killed")) - monkeypatch.setattr(repo, "run_cmd", fake) + monkeypatch.setattr(repo, "run_cmd", _answer_push_url(fake)) monkeypatch.setattr(repo, "run_cmd_with_backoff", fake) monkeypatch.setattr(repo, "_install_commit_hook", lambda repo_dir: None) # The clone is faked here, so the real workspace never gets a @@ -645,7 +669,7 @@ def test_baseline_build_genuine_failure_still_marks_regression_baseline(self, mo # Guard the other side: a REAL red build (exit 1, not an infra signal) must # still record build_before=False so genuine regressions are gated. fake = self._RecordingFake(rc_on=("verify-build-pre", 1, "TS2345: type error")) - monkeypatch.setattr(repo, "run_cmd", fake) + monkeypatch.setattr(repo, "run_cmd", _answer_push_url(fake)) monkeypatch.setattr(repo, "run_cmd_with_backoff", fake) monkeypatch.setattr(repo, "_install_commit_hook", lambda repo_dir: None) # The clone is faked here, so the real workspace never gets a @@ -677,7 +701,7 @@ def run_cmd(cmd, label, **kwargs): return fake(cmd, label, **kwargs) _patch_common(monkeypatch, fake) - monkeypatch.setattr(repo, "run_cmd", run_cmd) + monkeypatch.setattr(repo, "run_cmd", _answer_push_url(run_cmd)) monkeypatch.setattr(repo, "detect_default_branch", lambda url, d: "main") setup = repo.setup_repo( @@ -887,7 +911,7 @@ class TestSetupRepoDependencyUnreachable: def _patch_backoff_to_fail(self, monkeypatch, fake, *, transient_stderr): """Wire run_cmd_with_backoff to a real bounded loop over the fake so the report/raise path fires, while run_cmd (non-clone commands) stays faked.""" - monkeypatch.setattr(repo, "run_cmd", fake) + monkeypatch.setattr(repo, "run_cmd", _answer_push_url(fake)) monkeypatch.setattr(repo, "_install_commit_hook", lambda repo_dir: None) # The clone is faked here, so the real workspace never gets a # `.git`. Stub the pre-clean + git-root backstop (tested directly in @@ -930,7 +954,7 @@ def fake_run_cmd(cmd, label, cwd=None, timeout=600, check=True, **kwargs): # repo.run_cmd (the non-clone setup commands). run_cmd_with_backoff itself # is NOT patched — the real DNS-bail logic runs. monkeypatch.setattr("shell.run_cmd", fake_run_cmd) - monkeypatch.setattr(repo, "run_cmd", fake_run_cmd) + monkeypatch.setattr(repo, "run_cmd", _answer_push_url(fake_run_cmd)) monkeypatch.setattr(repo, "_install_commit_hook", lambda repo_dir: None) # The clone is faked here, so the real workspace never gets a # `.git`. Stub the pre-clean + git-root backstop (tested directly in @@ -1057,7 +1081,7 @@ def test_exhausted_pr_branch_fetch_reports_branch_as_resource(self, monkeypatch) transient fetch failure exhausts retries → dependency_unreachable naming the branch.""" fake = _fake_run_cmd() - monkeypatch.setattr(repo, "run_cmd", fake) + monkeypatch.setattr(repo, "run_cmd", _answer_push_url(fake)) monkeypatch.setattr(repo, "_install_commit_hook", lambda repo_dir: None) # The clone is faked here, so the real workspace never gets a # `.git`. Stub the pre-clean + git-root backstop (tested directly in @@ -1351,6 +1375,63 @@ def test_repo_bound_artifact_workflow_is_not_gated(self, monkeypatch): assert "push-preflight" not in fake.labels() assert "create-branch" in fake.labels() + def test_resolve_strategy_workflow_is_not_gated(self, monkeypatch): + # A custom workflow may be writeable yet only look up its PR (ensure_pr + # strategy resolve): its final step never pushes, so neither does setup check + # (#801 review). + from workflow import load_workflow + + base = load_workflow("coding/new-task-v1") + steps = [ + step.model_copy(update={"strategy": "resolve"}) if step.kind == "ensure_pr" else step + for step in base.steps + ] + resolve_wf = base.model_copy(update={"id": "synthetic/resolve-v1", "steps": steps}) + assert resolve_wf.read_only is False and resolve_wf.ensure_pr_strategy == "resolve" + fake = _PreflightFake(preflight_rc=128, preflight_stderr=_DENIED_403) + self._setup(monkeypatch, fake) + monkeypatch.setattr("workflow.load_workflow", lambda workflow_id: resolve_wf) + + repo.setup_repo(_config(resolved_workflow={"id": "synthetic/resolve-v1", "version": "1"})) + + assert "push-preflight" not in fake.labels() + + def test_push_url_is_pinned_to_https_before_the_check(self, monkeypatch): + fake = _PreflightFake() + self._setup(monkeypatch, fake) + + repo.setup_repo(_config()) + + assert fake.cmd_for("set-remote-push-url")[-1] == "https://github.com/owner/repo.git" + labels = fake.labels() + assert labels.index("set-remote-push-url") < labels.index("push-preflight") + assert fake.cmd_for("reset-git-credential-helpers")[-2:] == [ + "credential.https://github.com.helper", + "", + ] + + def test_rewritten_push_url_stops_setup(self, monkeypatch): + import pytest + + fake = _PreflightFake() + _patch_common(monkeypatch, fake) + monkeypatch.setattr(repo, "detect_default_branch", lambda url, d: "main") + + def rewritten(cmd, label, **kwargs): + result = fake(cmd, label, **kwargs) + if label == "get-remote-push-url": + return SimpleNamespace( + returncode=0, stdout="git@github.com:owner/repo.git\n", stderr="" + ) + return result + + monkeypatch.setattr(repo, "run_cmd", rewritten) + + with pytest.raises(RuntimeError, match="rewrites the push URL"): + repo.setup_repo(_config()) + + assert "push-preflight" not in fake.labels() + def test_repo_optional_artifact_workflow_with_a_repo_is_gated(self, monkeypatch): # default/agent-v1 declares primary: artifact but requires_repo: false; run # with a repository it still opens a PR, so it is checked. @@ -1401,8 +1482,8 @@ def test_classic_token_without_scopes_fails_before_the_agent_runs(self, monkeypa assert "classic personal access token" in message # Both cases: public_repo is enough for a public repository, and repo, which # also grants every private repository, only for a private one. - assert "`public_repo` scope if owner/repo is public, or `repo` if it is private" in message - assert "its owner needs write access to owner/repo" in message + assert "`public_repo` scope for a public repository, or `repo` for a private one" in message + assert "its owner needs write access to the repository" in message assert "Repository not found" in message assert "agent/README.md" in message assert token not in message @@ -1422,7 +1503,7 @@ def test_fine_grained_refusal_names_access_and_the_contents_permission(self, mon ) assert "fine-grained personal access token" in message - assert "include owner/repo in the token's repository access" in message + assert "include the repository in the token's repository access" in message assert "Contents permission with Read and write access" in message assert "Write access to repository not granted" in message @@ -1434,10 +1515,10 @@ def test_unknown_token_type_gets_both_remedies(self, monkeypatch): assert "`public_repo` scope" in message def test_github_app_token_remedy(self): - remedy = repo._token_remedy("ghs_" + "e" * 36, "owner/repo") + remedy = repo._token_remedy("ghs_" + "e" * 36) assert remedy.label == "GitHub App token" - assert "install it on owner/repo" in remedy.remedy + assert "install it on the repository" in remedy.remedy def test_rejected_credential_is_an_auth_failure_not_a_scope_problem(self, monkeypatch): # A token revoked or expired after the clone: GitHub rejects it at the push. @@ -1630,6 +1711,66 @@ def test_stacked_child_is_checked_before_its_base_is_fetched(self, monkeypatch): assert "fetch-base-branch" not in fake.labels() +class TestPushPreflightRedaction: + """#801 review: git's output is redacted before it is shortened. A cut can remove + the prefix the redactor recognizes a token by, and leave the rest in the clear.""" + + def test_timeout_warning_redacts_before_keeping_the_tail(self, monkeypatch, capfd): + import pytest + + token = "ghs_" + "Q" * 515 # 519 characters: the last 500 hold no ghs_ prefix + fake = _PreflightFake() + _patch_common(monkeypatch, fake) + + def timing_out(cmd, label, **kwargs): + raise subprocess.TimeoutExpired(cmd, 120, stderr=f"remote: {token}".encode()) + + monkeypatch.setattr(repo, "run_cmd_with_backoff", timing_out) + with pytest.raises(repo.DependencyUnreachableError): + repo._preflight_push_capability(_config(), "/nonexistent", progress=None) + + # log() writes with os.write, so only capfd sees it. + assert "Q" * 20 not in capfd.readouterr().out + + def test_refusal_excerpt_redacts_before_cutting(self): + # Keeping the head keeps a token's prefix, so this order guards the excerpt + # rather than closing a leak: the timeout tail above is the case that leaked. + token = "ghs_" + "R" * 300 + line = repo._quoted_line( + [f"remote: Permission to owner/repo.git denied. {token}"], ("permission to",) + ) + + assert "R" * 20 not in line + assert len(line) <= 200 + + def test_setup_failure_snippet_redacts_before_cutting(self): + import pytest + + token = "ghs_" + "S" * 600 + with pytest.raises(RuntimeError) as excinfo: + repo._fail_setup_command("push-preflight", "owner/repo", f"fatal: odd {token}", None) + + assert "S" * 20 not in str(excinfo.value) + + +class TestPushRefusalFitsTheTaskRecord: + """#801 review: the task record keeps the first 1,000 characters of the error + (task_state), and the classifier needs the sentence after the fix. The longest + message must fit: the longest owner/repo GitHub allows (39 + 1 + 100), a token of + no known type (the longest remedy), and a full 200-character git excerpt.""" + + def test_longest_refusal_fits(self): + repo_url = f"{'o' * 39}/{'r' * 100}" + stderr = f"remote: Permission to {repo_url}.git denied to someone. {'x' * 300}" + refusal = repo._push_refusal(_config(repo_url=repo_url, github_token=""), stderr) + + persisted = ( + f"PushCapabilityError: {refusal}" # as pipeline._chain_prior_agent_error stores it + ) + assert len(persisted) <= 1000, len(persisted) + assert "The task stopped before the agent ran" in persisted[:1000] + + class TestPushPreflightRetries: """Through the real bounded retry loop: a refusal fails in one attempt, an outage is retried.""" @@ -1798,7 +1939,7 @@ def test_only_the_tasks_token_answers_for_github(self, tmp_path, monkeypatch): monkeypatch.setenv("GIT_CONFIG_GLOBAL", str(global_cfg)) monkeypatch.setenv("PATH", f"{bin_dir}{os.pathsep}{os.environ['PATH']}") - repo._configure_git_credentials(str(work)) + repo._configure_git_credentials(str(work), "owner/repo") filled = subprocess.run( ["git", "credential", "fill"], @@ -1811,3 +1952,56 @@ def test_only_the_tasks_token_answers_for_github(self, tmp_path, monkeypatch): ).stdout assert "username=task-token" in filled assert not marker.exists() + + def test_push_url_ignores_push_insteadof_and_a_rewrite_is_refused(self, tmp_path, monkeypatch): + import pytest + + _, work = self._remote_and_clone(tmp_path, monkeypatch) + global_cfg = tmp_path / "global.gitconfig" + global_cfg.write_text('[url "git@github.com:"]\n\tpushInsteadOf = https://github.com/\n') + monkeypatch.setenv("GIT_CONFIG_GLOBAL", str(global_cfg)) + + repo._configure_git_credentials(str(work), "owner/repo") + + push_url = self._git("remote", "get-url", "--push", "origin", cwd=work).strip() + assert push_url == "https://github.com/owner/repo.git" + + # insteadOf rewrites even an explicit push URL: setup refuses rather than push + # with another credential. + global_cfg.write_text('[url "git@github.com:"]\n\tinsteadOf = https://github.com/\n') + with pytest.raises(RuntimeError, match="rewrites the push URL"): + repo._configure_git_credentials(str(work), "owner/repo") + + def test_helper_reset_is_scoped_to_github(self, tmp_path, monkeypatch): + # A login for another host in the same checkout keeps working (#801 review). + _, work = self._remote_and_clone(tmp_path, monkeypatch) + bin_dir = tmp_path / "bin" + bin_dir.mkdir() + (bin_dir / "gh").write_text( + "#!/bin/sh\ncat >/dev/null\necho username=task-token\necho password=x\n" + ) + (bin_dir / "saved-login").write_text( + "#!/bin/sh\ncat >/dev/null\necho username=saved-login\necho password=y\n" + ) + for f in bin_dir.iterdir(): + f.chmod(0o755) + global_cfg = tmp_path / "global.gitconfig" + global_cfg.write_text(f"[credential]\n\thelper = !{bin_dir}/saved-login\n") + monkeypatch.setenv("GIT_CONFIG_GLOBAL", str(global_cfg)) + monkeypatch.setenv("PATH", f"{bin_dir}{os.pathsep}{os.environ['PATH']}") + + repo._configure_git_credentials(str(work), "owner/repo") + + def fill(host): + return subprocess.run( + ["git", "credential", "fill"], + cwd=work, + input=f"protocol=https\nhost={host}\n\n", + capture_output=True, + text=True, + check=True, + env={**os.environ, "GIT_TERMINAL_PROMPT": "0"}, + ).stdout + + assert "username=task-token" in fill("github.com") + assert "username=saved-login" in fill("gitlab.example.com") diff --git a/cdk/test/handlers/shared/error-classifier.test.ts b/cdk/test/handlers/shared/error-classifier.test.ts index b011050cd..08076ff00 100644 --- a/cdk/test/handlers/shared/error-classifier.test.ts +++ b/cdk/test/handlers/shared/error-classifier.test.ts @@ -22,11 +22,14 @@ import { LAMBDA_MICROVM_SUPPORTED_REGIONS } from '../../../src/handlers/shared/m import { toTaskDetail, type TaskRecord } from '../../../src/handlers/shared/types'; // Persisted agent push preflight refusals, printed from agent/src/repo.py. -const MSG_CLASSIC = 'PushCapabilityError: Token cannot push to owner/repo: GitHub refused the classic personal access token write access (remote: Permission to owner/repo.git denied to ). To fix it, give the token the `public_repo` scope if owner/repo is public, or `repo` if it is private (`repo` grants every private repository its owner can reach); its owner needs write access to owner/repo. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; -const MSG_FINE = 'PushCapabilityError: Token cannot push to owner/repo: GitHub refused the fine-grained personal access token write access (remote: Permission to owner/repo.git denied to ). To fix it, include owner/repo in the token\'s repository access and give it the Contents permission with Read and write access; its owner needs write access to owner/repo. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; -const MSG_APP = 'PushCapabilityError: Token cannot push to owner/repo: GitHub refused the GitHub App token write access (remote: Permission to owner/repo.git denied to ). To fix it, give the app the Contents permission with Read and write access and install it on owner/repo. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; -const MSG_UNKNOWN = 'PushCapabilityError: Token cannot push to owner/repo: GitHub refused the GitHub token write access (remote: Permission to owner/repo.git denied to ). To fix it, for a fine-grained personal access token, include owner/repo in the token\'s repository access and give it the Contents permission with Read and write access; for a classic one, give the token the `public_repo` scope if owner/repo is public, or `repo` if it is private (`repo` grants every private repository its owner can reach); either way, its owner needs write access to owner/repo. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; -const MSG_DOTTED = 'PushCapabilityError: Token cannot push to owner/my.repo: GitHub refused the classic personal access token write access (remote: Permission to owner/my.repo.git denied to ). To fix it, give the token the `public_repo` scope if owner/my.repo is public, or `repo` if it is private (`repo` grants every private repository its owner can reach); its owner needs write access to owner/my.repo. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; +const MSG_CLASSIC = 'PushCapabilityError: Token cannot push to owner/repo: GitHub refused the classic personal access token write access (remote: Permission to owner/repo.git denied to ). To fix it, give the token the `public_repo` scope for a public repository, or `repo` for a private one (`repo` grants every private repository its owner can reach); its owner needs write access to the repository. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; +const MSG_FINE = 'PushCapabilityError: Token cannot push to owner/repo: GitHub refused the fine-grained personal access token write access (remote: Permission to owner/repo.git denied to ). To fix it, include the repository in the token\'s repository access and give it the Contents permission with Read and write access; its owner needs write access to the repository. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; +const MSG_APP = 'PushCapabilityError: Token cannot push to owner/repo: GitHub refused the GitHub App token write access (remote: Permission to owner/repo.git denied to ). To fix it, give the app the Contents permission with Read and write access and install it on the repository. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; +const MSG_UNKNOWN = 'PushCapabilityError: Token cannot push to owner/repo: GitHub refused the GitHub token write access (remote: Permission to owner/repo.git denied to ). To fix it, for a fine-grained personal access token, include the repository in the token\'s repository access and give it the Contents permission with Read and write access; for a classic one, give the token the `public_repo` scope for a public repository, or `repo` for a private one (`repo` grants every private repository its owner can reach); either way, its owner needs write access to the repository. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; +// The longest refusal: a 39 + 1 + 100 character owner/repo, a token of no known type and a +// full git excerpt, cut to the 1,000 characters the task record keeps (agent/src/task_state.py). +const MSG_LONGEST = 'PushCapabilityError: Token cannot push to ooooooooooooooooooooooooooooooooooooooo/rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr: GitHub refused the GitHub token write access (remote: Permission to ooooooooooooooooooooooooooooooooooooooo/rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr.git denied to xxxxxxxxxx). To fix it, for a fine-grained personal access token, include the repository in the token\'s repository access and give it the Contents permission with Read and write access; for a classic one, give the token the `public_repo` scope for a public repository, or `repo` for a private one (`repo` grants every private repository its owner can reach); either way, its owner needs write access to the repository. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; +const MSG_DOTTED = 'PushCapabilityError: Token cannot push to owner/my.repo: GitHub refused the classic personal access token write access (remote: Permission to owner/my.repo.git denied to ). To fix it, give the token the `public_repo` scope for a public repository, or `repo` for a private one (`repo` grants every private repository its owner can reach); its owner needs write access to the repository. The task stopped before the agent ran, so no work was lost. Token types and the permissions they need: agent/README.md, GitHub PAT — Minimal Permissions.'; describe('classifyError', () => { // --- Null / empty inputs --- @@ -156,11 +159,13 @@ describe('classifyError', () => { // web console's failure banner shows) carries the agent's fix, not the generic // fine-grained-PAT remedy of the orchestrator's message (#801 review). test.each([ - ['a classic PAT', MSG_CLASSIC, 'owner/repo', ['`public_repo` scope if owner/repo is public', '`repo` if it is private', 'its owner needs write access']], + ['a classic PAT', MSG_CLASSIC, 'owner/repo', ['`public_repo` scope for a public repository', '`repo` for a private one', 'its owner needs write access']], ['a fine-grained PAT', MSG_FINE, 'owner/repo', ['repository access', 'Contents permission with Read and write access']], - ['a GitHub App token', MSG_APP, 'owner/repo', ['install it on owner/repo']], + ['a GitHub App token', MSG_APP, 'owner/repo', ['install it on the repository']], ['an unknown token type', MSG_UNKNOWN, 'owner/repo', ['For a fine-grained personal access token', 'for a classic one']], - ['a repository with a dot in its name', MSG_DOTTED, 'owner/my.repo', ['its owner needs write access to owner/my.repo']], + ['a repository with a dot in its name', MSG_DOTTED, 'owner/my.repo', ['its owner needs write access to the repository']], + // The record is cut at 1,000 characters; the sentence the pattern needs must survive (#801 review). + ['the longest refusal, as stored', MSG_LONGEST, 'ooooooooooooooooooooooooooooooooooooooo/rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr', ['For a fine-grained personal access token', 'for a classic one']], ])('carries the agent push preflight fix for %s (#801)', (_label, message, repo, fragments) => { const result = classifyError(message); expect(result!.title).toBe('Insufficient GitHub token scopes'); @@ -1382,7 +1387,7 @@ describe('classifyError', () => { // web/src/core/util/progress.ts shows `${description} What to do: ${remedy}`. const detail = toTaskDetail({ ...baseRecord, error_message: MSG_APP }); expect(detail.error_classification!.description).toContain('GitHub App token'); - expect(detail.error_classification!.remedy).toContain('install it on owner/repo'); + expect(detail.error_classification!.remedy).toContain('install it on the repository'); expect(detail.error_classification!.remedy).not.toContain('fine-grained'); expect(detail.error_classification!.remedy).not.toContain('Update the PAT'); });