Native Git Gateway
Maintain Engineering Git transport, capability exchange, smart HTTP proxying, staged pushes, and enforcement boundaries.
Native Git is an Engineering repository transport layered on the existing GitHub integration. It is not another control-plane CLI and does not replace the GitHub MCP.
Ownership Flow
GitHub integration ID in the task manifest
→ backend authorization and native-Git resolution
→ short-lived integration gateway capability
→ per-run Git URL and header configuration
→ internal smart-HTTP gateway
→ fixed GitHub.com HTTPS origin with the backend-held PAT- The Git catalog owns the GitHub integration’s profile grants, authentication contract, and setup guidance.
- The backend owns authorization, credential decryption, GitHub origin selection, request validation, actions, and staged push bytes.
- The agent adapter owns ephemeral Git configuration for the active run only.
- GitHub owns repository graph rules and protected-branch enforcement.
The PAT must never enter the agent process, workspace, remote URL, command line, or logs.
Runtime Resolution
managedIntegrationRuntimes.github.nativeGit.profileKeys grants native Git only to Engineering.
Immediately before harness startup, the backend revalidates the organization, profile, integration,
credential, access mode, task mode, authorization epoch, and task version.
The adapter configures Git through session-local GIT_CONFIG_* values:
- rewrite
https://github.com/to the scoped internal gateway; - attach the short-lived gateway capability as an HTTP header; and
- disable interactive credential prompting.
The repository retains its ordinary GitHub HTTPS remote. Do not persist the rewritten gateway URL or mutate shared Git configuration.
Access Matrix
| Operation | Profile | Run Kind and Mode | Permission Mode |
|---|---|---|---|
| Upload-pack advertisement and RPC | Engineering | Task in plan, execute, research, or review | Any |
| Receive-pack advertisement and RPC | Engineering | Task in execute | Ask before writes or Autonomous |
| Any Git transport | Any other profile, chat, or verify | Any | Rejected |
Internal Routes
Keep the route namespace transport-first, parallel to the MCP and CLI gateways:
| Method | Route | Purpose |
|---|---|---|
GET | /internal/git/integrations/:integrationId/:owner/:repository/info/refs | Advertise upload-pack or receive-pack. |
POST | /internal/git/integrations/:integrationId/:owner/:repository/git-upload-pack | Stream a bounded repository read. |
POST | /internal/git/integrations/:integrationId/:owner/:repository/git-receive-pack | Validate, stage, and propose or execute a branch push. |
Do not move these endpoints under /internal/integrations/git. The transport owns the protocol
handler and the integration ID is its scoped resource.
The gateway builds only https://github.com/<owner>/<repository>.git, forwards reviewed headers,
uses manual redirect handling, and never accepts an arbitrary upstream URL.
Receive-pack Action Flow
- Accept at most 100 MiB.
- Parse the packet-line command section before staging.
- Accept at most 20 unique
refs/heads/*updates. - Reject tags, deletions, invalid or duplicate refs, later capability declarations, and push options.
- Hash the complete request and stage it privately under a backend-derived organization/run/integration/SHA-256 key.
- Persist only bounded typed action metadata; never persist an agent-selected object key or pack bytes in action JSON.
- Revalidate authorization, content type, size, and hash immediately before execution.
- Stream the staged request once to GitHub and bound the response to 1 MiB.
- Return GitHub’s exact report-status bytes to Git.
- Remove staged bytes after success, rejection, reconciliation, or terminal preparation failure.
Approval-required and unknown actions are rendered as valid Git report-status failures containing
the exact action ID. The Engineering skill follows task-runtime by preserving its disposable
source handoff, submitting action_interrupt, and stopping without retry.
Force-push Boundary
The receive-pack command contains the old object ID, new object ID, and ref. It does not identify
whether the client supplied --force or --force-with-lease.
Therefore:
- the Engineering skill instructionally prohibits force flags and history rewriting;
- the gateway mechanically rejects tags, deletions, unsupported refs, and push options; and
- GitHub branch protection or rulesets provide hard graph-aware non-fast-forward enforcement.
Do not add backend repository clones or commit-graph evaluation without a new product requirement that justifies the operational and storage cost.
Change Checklist
When changing this transport:
- Update shared runtime/action types before app consumers.
- Keep gateway authorization and GitHub origin selection backend-owned.
- Keep object keys canonical in
@oblive/objectstore. - Preserve protocol-native Git responses for approval, reconciliation, and upstream results.
- Update the Engineering skill, GitHub setup guidance, OpenAPI, user documentation, architecture references, and this guide together.
- Test runtime configuration, access modes, header sanitization, ref parsing, size bounds, private staging, action execution, cleanup, approval, unknown outcomes, and redirects.
Verification
bun test apps/agents/tests/codex.adapter.test.ts
bun test apps/backend/tests/services/git-gateway.service.test.ts
bun test apps/backend/tests/routes/integration-gateway.route.test.ts
bun test packages/agent-packs/tests/catalog.test.ts
bun run check:all