diff --git a/agent/README.md b/agent/README.md index 9698d980b..eeb2ac578 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 @@ -54,6 +56,22 @@ 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. 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 | +| 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. 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 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 The agent uses Amazon Bedrock for Claude inference. You need credentials with `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` permissions. diff --git a/agent/src/pipeline.py b/agent/src/pipeline.py index 2f2fa4487..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", @@ -1535,14 +1533,11 @@ def _on_trace_truncated(max_bytes: int, first_dropped: int) -> None: # branch, but default/agent-v1 is repo-OPTIONAL — run WITH a repo it # 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. The - # resolved value, as in build_config: a coding workflow may leave the - # line out, and the raw field is then None. - artifact_workflow = bool( - _workflow - and _workflow.terminal_outcomes.primary == "artifact" - and _workflow.resolved_requires_repo - ) + # repo-optional default-agent run would wrongly skip its PR. The rule is + # Workflow.delivers_repo_artifact (the resolved requires_repo, as in + # build_config: a coding workflow may leave the line out), which the push + # preflight in repo.setup_repo applies too, so a task it skips 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 3e201e05e..ca80a3710 100644 --- a/agent/src/repo.py +++ b/agent/src/repo.py @@ -1,8 +1,9 @@ """Repository setup: clone, branch, mise install, initial build.""" import os +import re import subprocess -from typing import Any +from typing import Any, NamedTuple, NoReturn from config import AGENT_WORKSPACE from models import RepoSetup, TaskConfig @@ -62,8 +63,8 @@ class DependencyUnreachableError(RuntimeError): error classifier attaches a precise remedy.""" -def _fail_setup_command(label: str, resource: str, stderr: str, progress: Any) -> None: - """Handle a failed clone/fetch after bounded retries. +def _fail_setup_command(label: str, resource: str, stderr: str, progress: Any) -> NoReturn: + """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 @@ -115,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. @@ -140,6 +143,417 @@ def _fail_setup_command(label: str, resource: str, stderr: str, progress: Any) - ) +class PushCapabilityError(RuntimeError): + """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). Per ``cause``: + + - ``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 +# 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" + +# 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", + "the requested url returned error: 403", + "the requested url returned error: 404", + "repository not found", +) + +# 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 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 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", + ( + "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): + label: str # the token type, as the error names it + remedy: str + + +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. 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 = ( + "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 = ( + "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}") + if token.startswith("ghp_"): + return _TokenRemedy("classic personal access token", f"{classic}; {owner}") + if token.startswith(("ghs_", "ghu_")): + return _TokenRemedy( + "GitHub App token", + "give the app the Contents permission with Read and write access and install " + "it on the repository", + ) + return _TokenRemedy( + "GitHub token", + f"for a fine-grained personal access token, {fine_grained}; for a classic one, " + f"{classic}; either way, {owner}", + ) + + +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 + + 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 "")) + # 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: + """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 = _quoted_line(lines, _CREDENTIAL_REJECTED_SIGNATURES) + return PushCapabilityError( + format_blocker_reason( + "auth_failure", + 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, + ), + cause="credential_rejected", + ) + if any(sig in low for sig in _PUSH_REFUSED_SIGNATURES): + 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, " + f"{remedy}. {no_loss} Token types and the permissions they need: " + "agent/README.md, GitHub PAT — Minimal Permissions.", + cause="no_write", + ) + return None + + +def _preflight_probe_commit(repo_dir: str) -> str: + """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'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", + 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 _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: + # 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: + _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, + ) + + +_GITHUB = "https://github.com" + + +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", helper_key, ""], + label="reset-git-credential-helpers", + cwd=repo_dir, + ) + run_cmd( + ["git", "config", "--local", "--add", helper_key, "!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``). 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 + 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 or workflow.ensure_pr_strategy == "resolve") + + +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). + + 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: 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 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. + + 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 not _task_pushes(config): + return + + log("SETUP", f"Checking that the GitHub token can push to {config.repo_url}...") + 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 from a global core.hooksPath or a git + # template may block or slow it. + "--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 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: + _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 + # 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) + + def _prepare_clone_dir(repo_dir: str, notes: list[str]) -> None: """Guarantee a clean slate at *repo_dir* before cloning. @@ -330,11 +744,10 @@ 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, 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) # Branch setup head_sha_before = "" diff --git a/agent/src/shell.py b/agent/src/shell.py index 9bf5dbad6..2b23379fe 100644 --- a/agent/src/shell.py +++ b/agent/src/shell.py @@ -487,6 +487,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/src/workflow/models.py b/agent/src/workflow/models.py index d9b9a757c..066ed12c9 100644 --- a/agent/src/workflow/models.py +++ b/agent/src/workflow/models.py @@ -242,3 +242,28 @@ def resolved_requires_repo(self) -> bool: if self.requires_repo is not None: 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. + + 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. + Uses ``resolved_requires_repo``, as ``build_config`` does: a ``coding`` + workflow may leave ``requires_repo`` out, and the raw field is then None. + """ + return self.terminal_outcomes.primary == "artifact" and self.resolved_requires_repo diff --git a/agent/tests/test_repo.py b/agent/tests/test_repo.py index 8c978f3de..804db27ba 100644 --- a/agent/tests/test_repo.py +++ b/agent/tests/test_repo.py @@ -9,6 +9,7 @@ """ import functools +import os import subprocess from types import SimpleNamespace @@ -30,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. @@ -46,6 +64,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" def _git(*args: str, cwd) -> str: @@ -106,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) @@ -146,10 +174,18 @@ 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 "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" + ) # Derived branch slug for a new task. assert setup.branch.startswith("bgagent/task-abc/") @@ -543,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 @@ -565,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 @@ -584,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 @@ -610,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 @@ -633,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 @@ -665,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( @@ -875,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 @@ -918,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 @@ -1045,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 @@ -1151,3 +1187,821 @@ 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 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 = "", 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, stderr=b"stalled") + return SimpleNamespace( + returncode=self._preflight_rc, stdout="", stderr=self._preflight_stderr + ) + return result + + +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/'" +) +_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" +) +_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: + """#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 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 _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), 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", github_token=token)) + + 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 running. + assert cmd[:4] == ["git", "push", "--dry-run", "--no-verify"] + assert cmd[4] == "origin" + # 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 == 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 token 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() + 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: 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) + + 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_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 coding 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 _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_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. + 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. + fake = _PreflightFake(preflight_rc=0) + self._setup(monkeypatch, fake) + + repo.setup_repo(_config(github_token="github_pat_" + "a" * 20)) + + assert "create-branch" in fake.labels() + + 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): + token = "ghp_" + "b" * 36 + 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 + # 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 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 + # No later setup step ran: no branch, no mise install, no build. + assert fake.labels()[-1] == "push-preflight" + + 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_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 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 + + def test_unknown_token_type_gets_both_remedies(self, monkeypatch): + # No token in the config: gh supplies whatever it is logged in with. + _, message = self._raises(monkeypatch, _DENIED_403, github_token="") + + assert "Contents permission" in message + assert "`public_repo` scope" in message + + def test_github_app_token_remedy(self): + remedy = repo._token_remedy("ghs_" + "e" * 36) + + assert remedy.label == "GitHub App token" + 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. + # 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 + + 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("Repository owner/repo is archived on GitHub, so it is read-only") + assert "Token cannot push" 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) + + assert message.startswith("GitHub organization policy blocks pushes to owner/repo") + assert "SAML single sign-on" in message + assert "Configure SSO" 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) + + 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 "`public_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) + + 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 + _, message = self._raises( + monkeypatch, f"remote: Permission to owner/repo.git denied. Token {leaked}" + ) + + assert leaked not in message + + 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, 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: 429", + 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(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(), progress=progress) + + 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/acme/archived-x.git/': " + "Could not resolve host: github.com", + exc=repo.DependencyUnreachableError, + repo_url="acme/archived-x", + ) + + 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): + # 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) + + 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( + 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 "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.""" + + 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 reaches the remote, passes, changes nothing, and does not depend on HEAD or on + hooks.""" + + @staticmethod + def _git(*args, cwd): + return subprocess.run( + ["git", *args], cwd=cwd, capture_output=True, text=True, check=True + ).stdout + + 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") + 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=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 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_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. + 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) + hooks = tmp_path / "hooks" + hooks.mkdir() + marker = tmp_path / "hook-ran" + 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) + + 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), "owner/repo") + + 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() + + 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/agent/tests/test_shell.py b/agent/tests/test_shell.py index 35c72911f..6d4a3a8f1 100644 --- a/agent/tests/test_shell.py +++ b/agent/tests/test_shell.py @@ -187,6 +187,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 6c9a0cea1..07084a903 100644 --- a/cdk/src/handlers/shared/error-classifier.ts +++ b/cdk/src/handlers/shared/error-classifier.ts @@ -248,6 +248,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: { @@ -908,6 +933,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: )`` @@ -1066,6 +1115,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 9fd0713bb..08076ff00 100644 --- a/cdk/test/handlers/shared/error-classifier.test.ts +++ b/cdk/test/handlers/shared/error-classifier.test.ts @@ -21,6 +21,16 @@ import { classifyError, ErrorCategory, ErrorClass, formatMicrovmTerminalFailure, 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 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 --- @@ -102,6 +112,78 @@ describe('classifyError', () => { expect(result!.title).toBe('Insufficient GitHub token scopes'); }); + // The errors agent/src/repo.py raises (PushCapabilityError) when GitHub refuses + // 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([ + [ + 'a token without write access', + MSG_CLASSIC, + 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); + }); + + // 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 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 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 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'); + 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); @@ -1301,6 +1383,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 the repository'); + 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/docs/design/SECURITY.md b/docs/design/SECURITY.md index 440e837b5..fd72b7139 100644 --- a/docs/design/SECURITY.md +++ b/docs/design/SECURITY.md @@ -157,6 +157,7 @@ flowchart LR | Pre-flight | GitHub access, PAT permissions, PR access | `preflight.ts` | `preflight_failed` event | | Hydration | Guardrail prompt screening | `context-hydration.ts` | `guardrail_blocked` event | | 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 672d51683..d4847c794 100644 --- a/docs/guides/USER_GUIDE.md +++ b/docs/guides/USER_GUIDE.md @@ -1205,7 +1205,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 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 9f7800041..c368c5a45 100644 --- a/docs/src/content/docs/architecture/Security.md +++ b/docs/src/content/docs/architecture/Security.md @@ -159,6 +159,7 @@ flowchart LR | Pre-flight | GitHub access, PAT permissions, PR access | `preflight.ts` | `preflight_failed` event | | Hydration | Guardrail prompt screening | `context-hydration.ts` | `guardrail_blocked` event | | 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 475241563..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. 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