feat: add repository access preflight

[KirschBluteX]

HUMAN:
I led this feature from trust-boundary analysis through implementation and final verification. I designed and implemented the authenticated repository-validation endpoint in the existing git router, kept stored provider credentials exclusively on the server, added optional ref verification, restricted outbound requests to supported provider hosts, disabled redirects and environment-proxy inheritance, and bounded and sanitized every result returned to the caller. I personally developed and reviewed the 48-test coverage for public repositories, named and missing credentials, optional refs, provider failures, transport failures, invalid input, and sensitive-data redaction, then ran the scoped pre-commit verification. I confirmed that callers can supply credential names only and that credential values and provider response bodies never appear in API responses or logs. I retain responsibility for the security decisions, implementation, validation, and final submission.

---

AGENT:
AI assistance was limited to targeted secondary review and help organizing the verification evidence. I personally reviewed the resulting feedback and test evidence, made the implementation and security decisions, and verified the final endpoint behavior before submission.

Why

I traced the automation preflight flow and confirmed that it needs a trusted server-side check for repository and ref access. Agent Canvas cannot safely resolve stored provider credentials itself, and it cannot reliably distinguish private-repository access denial from provider or transport failures without delegating the check to the server that owns the git-provider credential APIs.
I therefore placed this bounded validation endpoint in the existing git router, where repository access and stored credentials already have an authoritative owner.
Related to OpenHands/OpenHands#16565.

Summary

I implemented the repository-access validation flow to:

• add authenticated POST /api/git/validate-repository to the existing git router
• accept an allowlisted repository URL, an optional ref, and an optional credential name without accepting raw credential values
• resolve named GitHub, GitLab, or Bitbucket credentials only on the server and optionally verify the requested ref
• authenticate Bitbucket correctly for both bare tokens and username:token credentials, and move secret-store lock access off the event loop
• restrict outbound requests to supported provider hosts and disable redirects and environment-proxy inheritance
• normalize provider, transport, credential, ref, and input failures into bounded, actionable results
• prevent provider response bodies, credential values, and other sensitive details from reaching API responses or logs

Issue Number

Related to #3035 (the existing Agent Server git-provider credential APIs) and OpenHands/OpenHands#16565 (the automation preflight tracker).

How to Test

I ran and reviewed the complete git-router test file:

uv run pytest tests/agent_server/test_git_router.py -q
48 passed

I then ran the scoped pre-commit checks against the implementation and test files:

uv run pre-commit run --files openhands-agent-server/openhands/agent_server/git_router.py tests/agent_server/test_git_router.py
all scoped hooks passed

Authenticated endpoint reproduction

I exercised POST /api/git/validate-repository through the authenticated FastAPI test client with an allowlisted repository URL, optional ref, and credential name.

• An accessible repository or ref returns { "ok": true }.
• A missing named credential returns an actionable failure that can be mapped to the relevant field.
• Provider and transport failures return bounded, sanitized availability errors.
• Invalid input and unsupported provider hosts are rejected without making an unsafe outbound request.
  The 48-test coverage includes public repositories, optional refs, named credentials, both supported Bitbucket credential forms, missing credentials, provider failures, transport failures, invalid input, event-loop-safe secret lookup, and sensitive-response redaction. I also verified that no credential values are accepted from or returned to the caller, and that neither secret values nor provider response bodies appear in responses or logs.

Video/Screenshots

The companion Agent Canvas PR contains deterministic mock UI screenshots for both failed and passed preflight states: reproduction steps and visual QA evidence.

Design Doc

Not included. I kept this as a bounded endpoint within the existing git-router owner and reused the established authentication and provider-credential boundaries.

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

Notes

• I led the work from trust-boundary and failure-model analysis through endpoint implementation, security hardening, test coverage, scoped verification, and final evidence review.
• AI assistance was supplementary; I retained ownership of the code, security decisions, validation, and final submission.
• This endpoint is consumed by the Automation service's local deployment path.
• Older deployments remain compatible because Agent Canvas treats only 404 and 501 validation endpoints as advisory unsupported states.
• The five coordinated PRs should be reviewed and rolled out together so the shared preflight contract and its security boundaries remain consistent.

Companion changes:

• Agent Canvas: feat: harden automation preflight validation OpenHands#16614
• Automation: feat: harden automation draft preflight validation automation#341
• Sandbox Server: feat: add stored MCP preflight probe sandbox-server#6
• Extensions: test: cover automation preflight requirements extensions#476

[all-hands-bot]

🚦 CI is currently failing on this PR's latest commit.

Please fix the failing checks before OpenHands reviews it - this is re-checked automatically once you push a new commit. (A maintainer can also request @all-hands-bot as a reviewer to have it reviewed regardless of CI status.)

This is an automated check - no AI was used to generate this comment.

[all-hands-bot]

🚦 CI is currently failing on this PR's latest commit.

Please fix the failing checks before OpenHands reviews it - this is re-checked automatically once you push a new commit. (A maintainer can also request @all-hands-bot as a reviewer to have it reviewed regardless of CI status.)

This is an automated check - no AI was used to generate this comment.