fix: Return user OAuth token as primary for git/gh operations #112

agent-relay · 2026-01-08T18:53:43Z

Summary

Return userToken (user OAuth) as primary token field instead of installation token
Installation tokens (ghs_*) are API-only and don't work with git credential helpers
Both tokens still available via explicit fields for different use cases
Updates credential helpers to prefer userToken

Changes

src/cloud/api/git.ts:

token now returns userToken || installationToken (user token preferred)
Added tokenType field ('user' or 'installation') for transparency
Added installationToken field so API consumers can still use it if needed
POST endpoint now also fetches user tokens

deploy/workspace/git-credential-relay:

Prefers .userToken field, falls back to .token
Logs token type for debugging

deploy/workspace/gh-relay:

Prefers .userToken field, falls back to .token

Test plan

Verify git push works transparently (no URL embedding)
Verify gh pr create works transparently
Verify token expiry and refresh still works
Verify installation token still available for API operations

🤖 Generated with Claude Code

Installation tokens (ghs_*) are API-only and don't work with git credential helpers. This change: - Returns userToken as primary `token` field (falls back to installationToken) - Adds `tokenType` field so clients know what they got - Updates git-credential-relay to prefer userToken - Updates gh-relay to prefer userToken Both tokens still available via explicit fields: - `userToken` - User OAuth token (works for git + gh CLI) - `installationToken` - GitHub App token (works for API only) Fixes: git push and gh pr create now work transparently 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

Follow-up task for PR #112 - document how agents should use userToken vs installationToken from /api/git/token response. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Problem: /api/git/token returned installation tokens (API-only) - Solution: Return dual tokens (userToken for git, installationToken for API) - Implementation: Modified endpoint and credential helpers - Impact: Unblocks all agent git workflows, enables GitHub App integration - Related: PR #112, bd-git-auth-fix, bd-git-auth-docs Trail ID: traj_pdreuiy4xr4i Confidence: 92%

Copilot

Pull request overview

This PR fixes git authentication by returning user OAuth tokens instead of GitHub App installation tokens as the primary token. Installation tokens (ghs_*) only work with GitHub's REST API and fail with git credential helpers, requiring manual token embedding in URLs. The fix ensures git push, pull, and gh CLI commands work transparently by preferring user tokens while maintaining backward compatibility.

Key changes:

Modified /api/git/token GET and POST endpoints to return userToken as primary token with fallback to installation token
Added tokenType field for transparency and explicit installationToken field for API operations
Updated credential helpers to prefer userToken field

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/cloud/api/git.ts	Modified token response structure to prefer userToken over installationToken, added tokenType field, updated both GET and POST endpoints
deploy/workspace/git-credential-relay	Updated to prefer userToken field with fallback to token field, added token type logging
deploy/workspace/gh-relay	Updated to prefer userToken field with fallback to token field
TRAIL_GIT_AUTH_FIX.md	Added comprehensive documentation of the problem, solution, and implementation details
.beads/beads.jsonl	Added new bead entries for git auth fix and documentation tasks

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-08T21:30:46Z

.beads/beads.jsonl

 {"id":"agent-relay-325","title":"Mobile header not sticky when test input open and scrolling","description":"On mobile, the header isn't truly sticky. When user opens the test input and scrolls down, the header disappears.\n\n## Steps to Reproduce\n1. Open dashboard on mobile\n2. Open the test input\n3. Scroll down\n4. Header disappears (should stay sticky)\n\n## Expected Behavior\nHeader should remain sticky/fixed at top even when test input is open and user scrolls.\n\n## Investigation Needed\n1. Check header z-index vs test input z-index\n2. Check if test input container creates new stacking context\n3. Verify sticky positioning works with whatever container wraps the scrollable area\n4. May need position: fixed instead of sticky, or adjust container overflow\n\n## Files\n- src/dashboard/react-components/layout/Header.tsx\n- Related input/modal components","priority":70,"status":"open","created_at":"2026-01-05T23:15:00Z","tags":["bug","mobile","ui","header"],"depends_on":[]}
+{"id":"bd-git-auth-fix","title":"Fix Git and GitHub CLI Authentication - Credential Helper Chain","description":"GitHub API operations (git push, gh CLI) fail due to installation tokens not supporting credential helpers.\n\n## Problem\n- /api/git/token endpoint returns GitHub App installation tokens (ghs_*)\n- Installation tokens don't work with git credential helpers (GitHub limitation)\n- Workaround required: embed token directly in HTTPS URL\n- This wastes cycles and breaks automated workflows\n\n## Current Behavior (Broken)\n```bash\ngit config credential.helper /usr/local/bin/git-credential-relay\ngit push origin branch  # FAILS: \"Password authentication not supported\"\n```\n\n## Current Workaround (Unsustainable)\n```bash\nTOKEN=$(curl -s ... /api/git/token)\ngit push \"https://x-access-token:${TOKEN}@github.com/org/repo.git\" branch\n```\n\n## Root Cause\n1. /api/git/token returns `installationToken` (type ghs_*) on line 182 of src/cloud/api/git.ts\n2. Installation tokens are API-only, not for git operations\n3. git-credential-relay expects a token that works, but gets incompatible one\n4. gh CLI wrapper relies on same broken endpoint\n\n## Solution Options\n1. **Option A (Preferred)**: Return userToken or PAT from /api/git/token\n   - Check if userToken is available from Nango\n   - Or generate a real PAT via GitHub API\n   - Keep installation token for API operations\n\n2. **Option B**: Fix git-credential-relay to handle token embedding\n   - Modify helper to inject token into URL automatically\n   - Less clean but might work as fallback\n\n3. **Option C**: Implement new token endpoint\n   - /api/git/pat for git operations\n   - Keep /api/git/token for API operations\n\n## Success Criteria\n- `git push origin branch` works transparently\n- `gh pr create` works transparently\n- Token refresh happens automatically (55-min cache)\n- No URL embedding workarounds needed\n- Agents can focus on work, not auth mechanics\n\n## Investigation Steps\n1. Check Nango service for PAT/user token availability\n2. Review userToken field in current /api/git/token response\n3. Test if userToken works for git operations\n4. If not, implement PAT generation from GitHub API\n5. Update git-credential-relay to use new token source\n6. Test with gh CLI wrapper\n\n## Files to Modify\n- src/cloud/api/git.ts (token endpoint)\n- src/cloud/services/nango.ts (token sources)\n- /usr/local/bin/git-credential-relay (helper)\n- deploy/workspace/gh-relay (gh CLI wrapper)","priority":100,"status":"open","created_at":"2026-01-08T18:30:00Z","tags":["critical","infrastructure","git-auth","automation","blocker"],"depends_on":[]}
+{"id":"bd-git-auth-docs","title":"Document Dual-Token Usage for Agents - userToken vs installationToken","description":"After PR #112 (git auth fix) merges, agents need clear documentation on which token to use for different operations.\n\n## What Changed\n/api/git/token now returns two tokens:\n- userToken: GitHub user OAuth token (for git push, git clone, gh CLI)\n- installationToken: GitHub App installation token (for app-specific API operations)\n\n## What Agents Need to Know\n1. **For Git Operations** (automatic)\n   - git push, git clone, git pull\n   - gh CLI commands (pr create, issue list, etc.)\n   - These automatically use userToken via credential helpers\n   - No agent action needed\n\n2. **For GitHub App API Operations** (if needed)\n   - Call GitHub App-specific endpoints\n   - Use installationToken from /api/git/token response\n   - Reference: https://docs.github.com/en/rest/apps\n   - Examples: list installations, manage webhooks, etc.\n\n## Documentation Needed\n1. API reference: /docs/api/git-token.md\n   - Explain both token types\n   - When to use each\n   - Response schema\n\n2. Agent guide: /docs/agents/github-operations.md\n   - Git operations (automatic, no setup needed)\n   - GitHub App API operations (when and how to use)\n   - Example code snippets\n\n3. Update inline comments in:\n   - src/cloud/api/git.ts\n   - deploy/workspace/git-credential-relay\n   - deploy/workspace/gh-relay\n\n## Success Criteria\n- Agents understand token purpose without asking\n- Clear examples for both use cases\n- Documentation discoverable from PR #112\n- Ready for future GitHub App integrations","priority":60,"status":"open","created_at":"2026-01-08T18:50:00Z","tags":["documentation","github-api","agents","follow-up"],"depends_on":["bd-git-auth-fix"]}
+{"id":"bd-git-auth-docs","title":"Document Dual-Token Usage for Git/GitHub Operations","description":"Create documentation for agents on how to use the dual-token response from /api/git/token.\n\n## Context\nPR #112 implemented dual-token response:\n- `userToken`: User OAuth token for git push, gh CLI, user-context operations\n- `installationToken`: GitHub App token for app-specific API calls\n- `token`: Primary token (userToken preferred, falls back to installationToken)\n- `tokenType`: 'user' or 'installation' to indicate which type was returned\n\n## Documentation Needed\n\n1. **Agent Usage Guide**\n   - Git operations: Automatic via credential helper (uses userToken)\n   - gh CLI operations: Automatic via gh-relay wrapper (uses userToken)\n   - GitHub App API calls: Use installationToken directly if needed\n\n2. **When to Use Each Token**\n   | Operation | Token to Use | Notes |\n   |-----------|--------------|-------|\n   | git push/pull/clone | userToken (automatic) | Credential helper handles this |\n   | gh pr create | userToken (automatic) | gh-relay wrapper handles this |\n   | gh issue create | userToken (automatic) | gh-relay wrapper handles this |\n   | List app installations | installationToken | GitHub App API only |\n   | App webhook management | installationToken | GitHub App API only |\n\n3. **Optional: Add usage hints to API response**\n   ```javascript\n   usage: {\n     token: 'Primary token for git/gh operations (auto-selected)',\n     userToken: 'User OAuth - for git push, gh CLI, user-context operations',\n     installationToken: 'GitHub App - for app-specific API calls only'\n   }\n   ```\n\n## Files to Create/Update\n- docs/api/git-token.md (new)\n- Optional: Update src/cloud/api/git.ts with usage hints in response\n\n## Depends On\n- PR #112 merged","priority":60,"status":"open","created_at":"2026-01-08T19:30:00Z","tags":["documentation","git-auth","follow-up"],"depends_on":["bd-git-auth-fix"]}


Duplicate bead ID 'bd-git-auth-docs' on lines 48 and 49. Each bead must have a unique identifier. The second entry should use a different ID.

Suggested change

{"id":"bd-git-auth-docs","title":"Document Dual-Token Usage for Git/GitHub Operations","description":"Create documentation for agents on how to use the dual-token response from /api/git/token.\n\n## Context\nPR #112 implemented dual-token response:\n- `userToken`: User OAuth token for git push, gh CLI, user-context operations\n- `installationToken`: GitHub App token for app-specific API calls\n- `token`: Primary token (userToken preferred, falls back to installationToken)\n- `tokenType`: 'user' or 'installation' to indicate which type was returned\n\n## Documentation Needed\n\n1. **Agent Usage Guide**\n - Git operations: Automatic via credential helper (uses userToken)\n - gh CLI operations: Automatic via gh-relay wrapper (uses userToken)\n - GitHub App API calls: Use installationToken directly if needed\n\n2. **When to Use Each Token**\n | Operation | Token to Use | Notes |\n |-----------|--------------|-------|\n | git push/pull/clone | userToken (automatic) | Credential helper handles this |\n | gh pr create | userToken (automatic) | gh-relay wrapper handles this |\n | gh issue create | userToken (automatic) | gh-relay wrapper handles this |\n | List app installations | installationToken | GitHub App API only |\n | App webhook management | installationToken | GitHub App API only |\n\n3. **Optional: Add usage hints to API response**\n ```javascript\n usage: {\n token: 'Primary token for git/gh operations (auto-selected)',\n userToken: 'User OAuth - for git push, gh CLI, user-context operations',\n installationToken: 'GitHub App - for app-specific API calls only'\n }\n ```\n\n## Files to Create/Update\n- docs/api/git-token.md (new)\n- Optional: Update src/cloud/api/git.ts with usage hints in response\n\n## Depends On\n- PR #112 merged","priority":60,"status":"open","created_at":"2026-01-08T19:30:00Z","tags":["documentation","git-auth","follow-up"],"depends_on":["bd-git-auth-fix"]}

{"id":"bd-git-auth-docs-usage","title":"Document Dual-Token Usage for Git/GitHub Operations","description":"Create documentation for agents on how to use the dual-token response from /api/git/token.\n\n## Context\nPR #112 implemented dual-token response:\n- `userToken`: User OAuth token for git push, gh CLI, user-context operations\n- `installationToken`: GitHub App token for app-specific API calls\n- `token`: Primary token (userToken preferred, falls back to installationToken)\n- `tokenType`: 'user' or 'installation' to indicate which type was returned\n\n## Documentation Needed\n\n1. **Agent Usage Guide**\n - Git operations: Automatic via credential helper (uses userToken)\n - gh CLI operations: Automatic via gh-relay wrapper (uses userToken)\n - GitHub App API calls: Use installationToken directly if needed\n\n2. **When to Use Each Token**\n | Operation | Token to Use | Notes |\n |-----------|--------------|-------|\n | git push/pull/clone | userToken (automatic) | Credential helper handles this |\n | gh pr create | userToken (automatic) | gh-relay wrapper handles this |\n | gh issue create | userToken (automatic) | gh-relay wrapper handles this |\n | List app installations | installationToken | GitHub App API only |\n | App webhook management | installationToken | GitHub App API only |\n\n3. **Optional: Add usage hints to API response**\n ```javascript\n usage: {\n token: 'Primary token for git/gh operations (auto-selected)',\n userToken: 'User OAuth - for git push, gh CLI, user-context operations',\n installationToken: 'GitHub App - for app-specific API calls only'\n }\n ```\n\n## Files to Create/Update\n- docs/api/git-token.md (new)\n- Optional: Update src/cloud/api/git.ts with usage hints in response\n\n## Depends On\n- PR #112 merged","priority":60,"status":"open","created_at":"2026-01-08T19:30:00Z","tags":["documentation","git-auth","follow-up"],"depends_on":["bd-git-auth-fix"]}

Agent Relay and others added 5 commits January 8, 2026 18:32

beads: Add git auth infrastructure fix task (bd-git-auth-fix)

a269313

beads: Add task for dual-token documentation (bd-git-auth-docs)

7ee90c8

khaliqgant requested a review from Copilot January 8, 2026 21:29

Copilot AI reviewed Jan 8, 2026

View reviewed changes

khaliqgant merged commit c59ea61 into main Jan 8, 2026
6 checks passed

khaliqgant deleted the fix/git-auth-infrastructure branch January 8, 2026 23:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: Return user OAuth token as primary for git/gh operations #112

fix: Return user OAuth token as primary for git/gh operations #112

Uh oh!

agent-relay bot commented Jan 8, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 8, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fix: Return user OAuth token as primary for git/gh operations #112

fix: Return user OAuth token as primary for git/gh operations #112

Uh oh!

Conversation

agent-relay bot commented Jan 8, 2026

Summary

Changes

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants