Skip to main content

​
Endpoint

POST /api/github/import
Imports a GitHub repository into a new Polaris project. This creates a project, clones the repository content, and processes all files asynchronously via Inngest background job.
This endpoint requires a Pro plan subscription.

​
Authentication

Requires:
  • Valid Clerk session token
  • GitHub OAuth connection via Clerk
  • Pro plan subscription

​
Request Body

​
url
string
required
The full GitHub repository URL (e.g., https://github.com/owner/repo).Supports both HTTPS and SSH URLs. The .git extension is optional.

​
Response

​
success
boolean
Indicates whether the import was successfully initiated.
​
projectId
string
The Convex ID of the created project.
​
eventId
string
The Inngest event ID for tracking the background import job.

​
Request Example

const response = await fetch('/api/github/import', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://github.com/vercel/next.js'
  })
});

const data = await response.json();
console.log(data.projectId);

​
Response Example

{
  "success": true,
  "projectId": "k57abc123def456",
  "eventId": "01HQXYZ789ABCDEF"
}

​
Import Process

The import happens asynchronously in the background:
1

Project creation

A new Polaris project is created with the repository name.
2

Repository cloning

The GitHub repository content is fetched using the GitHub API.
3

Folder structure

All folders are created in hierarchical order (parent folders first).
4

File processing

Files are imported:
  • Text files: Content stored in database
  • Binary files: Stored in Convex file storage
5

Status update

Project importStatus is updated to completed or failed.

​
Monitoring Import Status

Query the project to check import status: 
const project = await convex.query(api.projects.getById, { 
  id: projectId 
});

if (project.importStatus === 'completed') {
  console.log('Import finished!');
} else if (project.importStatus === 'failed') {
  console.log('Import failed');
} else {
  console.log('Still importing...');
}

​
Error Handling

GitHub import is a Pro feature. Upgrade your plan in the Polaris settings.
Reconnect your GitHub account in Clerk settings. The OAuth token may have expired.
Ensure the URL is in the format https://github.com/owner/repo or [email protected]:owner/repo.git.
Verify your GitHub OAuth token has access to the repository. You may need to grant additional permissions in GitHub settings.

​
Learn More

Build docs developers (and LLMs) love

Get started for freeTalk to us