GitHub Integration

Overview

The GitHub integration does two jobs for Praxiom AI. First, it grounds the agent in your actual codebase — seven read-only tools let the agent inspect files, directory trees, commits, and open PRs before making a recommendation, so suggestions match what's really in main rather than hallucinated shape. Second, it pushes recommendations out as GitHub issues, with a back-channel sync that flips recommendation status to implemented when the issue closes.

Connecting

{
  "workspace_id": "your-workspace-uuid"
}

GET /api/integrations/github/repos?workspace_id={id}&search=...&page=1

POST /api/integrations/github/repos/select

{
  "workspace_id": "your-workspace-uuid",
  "repos": ["org/repo-1", "org/repo-2"]
}

Agent Tools (Read)

These seven tools are what make GitHub more than a push target — the agent uses them to ground recommendations in the real code. All seven are read-only and do not go through HITL approval.

Error shape

All seven tools translate GitHubServiceError into a structured payload the agent can reason over:

{
  "success": false,
  "error": "Repository 'org/missing' not found or access denied.",
  "error_code": "not_found"
}

Common error_code values: not_found, forbidden, rate_limited (with retry_after), token_expired, too_large, unknown.

Agent Tools (Write)

create_github_issue is gated — calling it from the agent returns { status: "queued", pending_action_id }. The user approves the action from the pending-actions inbox; the executor then calls the __original__ handler with gating disabled.

Creating Issues (API)

Push a recommendation to GitHub as an issue:

POST /api/integrations/github/issues

{
  "workspace_id": "your-workspace-uuid",
  "recommendation_id": "rec-uuid",
  "repo": "org/repo-name",
  "title": "Improve onboarding flow",
  "body": "Based on user research...",
  "labels": ["enhancement", "priority:high"]
}

The endpoint validates the repo is in selected_repos (returns REPO_NOT_SELECTED otherwise), calls GitHubService.create_issue, and persists a RecommendationGitHubLink row with the issue number, URL, title, and state. The response includes the issue_url, issue_number, and the link_id used by sync.

Status Sync

POST /api/integrations/github/sync

{
  "workspace_id": "your-workspace-uuid"
}

For each link in the workspace, the endpoint calls GET /repos/{repo}/issues/{n}, updates github_issue_state and last_synced_at on the link, and — if the issue has a linked PR — stores github_pr_url. When an issue transitions to closed, the linked Recommendation.status is flipped to implemented (unless it was already implemented or rejected).

Response:

{
  "synced_count": 42,
  "updated_count": 3
}

Management Endpoints

Key Concepts

• Selected-repo firewall — the agent can only read and write to repos the user has explicitly picked. An unknown repo in any tool returns a typed error listing the available ones.
• Bidirectional traceability — every linked issue knows its source recommendation; every recommendation with a link knows its issue state. Close the loop from user evidence → recommendation → issue → merged PR.
• Truncation is visible — read tools always return truncated: bool and line/byte counts so the agent knows when it's only seen part of a file and can issue a follow-up slice.
• Gated writes — only create_github_issue is a write; it goes through the pending-actions queue so the user approves the title/body/labels/repo before anything hits GitHub.

What's Next

• Linear Integration — 9 agent tools for querying and updating tickets.
• Pending Actions — how HITL approval works for create_github_issue.
• Execution Tickets — bulk push workflow when you want to ship a whole document, not one recommendation.