Endpoint Exports a Polaris project to a new GitHub repository. This creates a new repository on GitHub and pushes all project 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 The Convex ID of the project to export.
The name for the new GitHub repository (1-100 characters). Must follow GitHub naming rules: alphanumeric, hyphens, and underscores only.
Repository visibility: public or private.
Optional repository description (max 350 characters).
Response Indicates whether the export was successfully initiated.
The Convex ID of the exported project.
The Inngest event ID for tracking the background export job.
Request Example const response = await fetch ( '/api/github/export' , { method: 'POST' , headers: { 'Content-Type' : 'application/json' , }, body: JSON . stringify ({ projectId: 'k57abc123def456' , repoName: 'my-polaris-project' , visibility: 'private' , description: 'Exported from Polaris IDE' }) }); const data = await response . json (); console . log ( data . eventId );
Response Example 200 Success
401 Unauthorized
403 Forbidden
400 Bad Request
{ "success" : true , "projectId" : "k57abc123def456" , "eventId" : "01HQXYZ789ABCDEF" }
Export Process The export happens asynchronously in the background:
Repository creation
A new GitHub repository is created with the specified name and visibility.
File collection
All project files are fetched from Convex database.
Blob creation
Files are uploaded to GitHub as blobs via the Git Database API.
Tree creation
A Git tree is created representing the complete folder structure.
Commit creation
An initial commit is created with message “Initial commit from Polaris”.
Branch update
The main branch is updated to point to the new commit.
Status update
Project exportStatus is updated to completed and exportRepoUrl is saved.
Monitoring Export Status Query the project to check export status:
const project = await convex . query ( api . projects . getById , { id: projectId }); if ( project . exportStatus === 'completed' ) { console . log ( 'Exported to:' , project . exportRepoUrl ); } else if ( project . exportStatus === 'failed' ) { console . log ( 'Export failed' ); } else if ( project . exportStatus === 'cancelled' ) { console . log ( 'Export was cancelled' ); } else { console . log ( 'Still exporting...' ); }
Cancelling Export You can cancel an in-progress export:
const response = await fetch ( '/api/github/export/cancel' , { method: 'POST' , headers: { 'Content-Type' : 'application/json' }, body: JSON . stringify ({ projectId }) });
Error Handling
GitHub export is a Pro feature. Upgrade your plan in the Polaris settings.
Reconnect your GitHub account in Clerk settings. The OAuth token may have expired.
Repository name already exists
Choose a different repository name. GitHub repository names must be unique within your account.
Export already in progress
Wait for the current export to complete or cancel it before starting a new one.
Learn More