Skip to main content

​
Overview

Polaris IDE integrates with GitHub to import existing repositories and export your projects. This enables seamless collaboration and version control for your cloud IDE projects.
GitHub integration uses the GitHub OAuth flow and requires a connected GitHub account.

​
Features

Import Repositories

Clone any public or private GitHub repository into Polaris IDE

Export Projects

Push your Polaris projects to new or existing GitHub repositories

OAuth Authentication

Secure authentication using GitHub OAuth with Stack Auth

Auto-create Repos

Automatically create repositories when exporting if they don’t exist

​
Setup

​
Connect GitHub Account

1

Navigate to Account Settings

Click your profile picture and select “Account Settings” or go to /handler/account-settings.
2

Connect GitHub

In the “Connected Accounts” section, click “Connect GitHub”.
3

Authorize Polaris

You’ll be redirected to GitHub to authorize Polaris IDE. Click “Authorize” to grant access.
4

Confirmation

Once authorized, you’ll be redirected back to Polaris. Your GitHub account is now connected!

​
Required Permissions

Polaris IDE requests the following GitHub scopes:
  • repo - Full control of private repositories
  • read:user - Read user profile information
  • user:email - Access user email addresses

​
Importing from GitHub

Import existing GitHub repositories into Polaris IDE:

​
Using the Dashboard

1

Go to Projects Dashboard

Navigate to the main dashboard at /.
2

Click Import from GitHub

Click the “Import from GitHub” button.
3

Enter Repository URL

Paste the full GitHub repository URL:
https://github.com/owner/repository
4

Import

Click “Import” and wait for the repository to be cloned. You’ll see a progress indicator.

​
Using the API

Import repositories programmatically using the GitHub import API: 
const response = await fetch('/api/github/import', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    repoUrl: 'https://github.com/owner/repository'
  })
});

const result = await response.json();

if (result.success) {
  console.log('Project created:', result.projectId);
} else {
  console.error('Import failed:', result.error);
}

​
Import Implementation

The import process follows these steps (src/app/api/github/import/route.ts:68):
1

Validate GitHub URL

Parse and validate the repository URL to extract owner and repo name.
2

Check Authentication

Verify the user has a connected GitHub account with valid token.
3

Check Project Limit

Verify the user hasn’t exceeded their project limit (uses Autumn billing).
4

Create Project

Create a new Convex project with the repository name.
5

Fetch Repository Contents

Use GitHub API to recursively fetch all files from the repository.
6

Import Files

Write each file to Convex using the internal file system API.
7

Track Usage

Increment the user’s project count for billing purposes.

​
URL Parsing

Supported GitHub URL formats: 
// HTTPS URLs
https://github.com/owner/repo
https://github.com/owner/repo.git

// SSH URLs
git@github.com:owner/repo.git

// All formats are normalized to extract owner and repo
Implementation: src/lib/github.ts (parseGitHubUrl function)

​
Exporting to GitHub

Push your Polaris projects to GitHub repositories:

​
Using the Project Menu

1

Open Project

Open the project you want to export.
2

Open Export Dialog

Click the project menu (three dots) and select “Export to GitHub”.
3

Configure Export

Repository URL:
https://github.com/your-username/repository-name
Options:
  • Create if not exists (auto-create repository)
  • Private repository (default: true)
  • Repository description (optional)
  • Commit message (default: “Update from Polaris”)
4

Export

Click “Export” and wait for the process to complete.

​
Using the API

Export projects programmatically: 
const response = await fetch('/api/github/export', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    projectId: 'k1234567890abcdef',
    repoUrl: 'https://github.com/your-username/my-project',
    commitMessage: 'Update from Polaris IDE',
    createIfNotExists: true,
    isPrivate: true,
    repoDescription: 'My awesome project'
  })
});

const result = await response.json();

if (result.success) {
  console.log('Export successful!');
} else {
  console.error('Export failed:', result.error);
}

​
Export Implementation

The export process (src/app/api/github/export/route.ts:66):
1

Validate Repository URL

Parse the GitHub URL and validate format.
2

Check Repository Existence

Use GitHub API to check if the repository exists.
3

Create Repository (Optional)

If createIfNotExists is true and repo doesn’t exist:
  • Create the repository with specified settings
  • Wait for GitHub to initialize the repo (2 second delay)
4

Update Export Status

Set project export status to “exporting” in Convex.
5

Fetch All Project Files

Retrieve all files from the Convex project.
6

Push to GitHub

Use GitHub Contents API to create/update files:
  • Create or update each file
  • Batch commits where possible
  • Handle file deletions if needed
7

Update Status

Set export status to “completed” or “failed” based on result.

​
Auto-create Repository

When exporting to a non-existent repository with createIfNotExists: true: 
const createResult = await createRepository(octokit, repo, {
  private: isPrivate,
  description: repoDescription,
  autoInit: true,  // Creates with README.md
});
Implementation: src/lib/github.ts (createRepository function)

​
GitHub API Integration

Polaris uses the Octokit REST client for GitHub API operations:

​
Client Creation

import { Octokit } from '@octokit/rest';

export function createOctokit(token: string): Octokit {
  return new Octokit({
    auth: token,
    userAgent: 'Polaris-IDE/1.0',
  });
}

​
Token Storage

GitHub OAuth tokens are stored securely in Stack Auth: 
// Get token for authenticated user
const token = await getGithubToken(userId);

if (!token) {
  throw new Error('GitHub not connected');
}

const octokit = createOctokit(token);

​
Token Validation

Validate stored tokens before use: 
const validation = await validateGitHubToken(octokit);

if (!validation.valid) {
  // Token expired or revoked - prompt user to reconnect
  console.error('Token invalid:', validation.error);
}
Implementation: src/lib/github.ts

​
API Endpoints

​
POST /api/github/import

Import a GitHub repository into Polaris IDE. Request: 
{
  "repoUrl": "https://github.com/owner/repository"
}
Response (Success): 
{
  "success": true,
  "projectId": "k1234567890abcdef"
}
Response (Error): 
{
  "error": "Invalid GitHub URL"
}
Status Codes:
  • 200 - Import successful
  • 400 - Invalid request (bad URL)
  • 401 - Unauthenticated
  • 403 - GitHub not connected or project limit reached
  • 500 - Import failed
File: src/app/api/github/import/route.ts:17

​
POST /api/github/export

Export a Polaris project to GitHub. Request: 
{
  "projectId": "k1234567890abcdef",
  "repoUrl": "https://github.com/owner/repository",
  "commitMessage": "Update from Polaris",
  "createIfNotExists": true,
  "isPrivate": true,
  "repoDescription": "Project description"
}
Response (Success): 
{
  "success": true
}
Response (Error): 
{
  "error": "Repository does not exist"
}
Status Codes:
  • 200 - Export successful
  • 400 - Invalid request
  • 401 - Unauthenticated
  • 403 - GitHub not connected
  • 404 - Repository not found (when createIfNotExists is false)
  • 500 - Export failed
File: src/app/api/github/export/route.ts:20

​
GET /api/github/status

Check GitHub connection status for the authenticated user. Response (Connected): 
{
  "connected": true,
  "username": "your-github-username"
}
Response (Not Connected): 
{
  "connected": false
}
File: src/app/api/github/status/route.ts:5

​
Import Status Tracking

Import operations update the project status in Convex: 
// Start import
await convex.mutation(api.system.updateProjectImportStatus, {
  projectId,
  status: "importing",
});

// Complete import
await convex.mutation(api.system.updateProjectImportStatus, {
  projectId,
  status: "completed",
});

// Handle errors
await convex.mutation(api.system.updateProjectImportStatus, {
  projectId,
  status: "failed",
});
Status values:
  • importing - Import in progress
  • completed - Import successful
  • failed - Import failed
Schema: convex/schema.ts:45

​
Export Status Tracking

Similar status tracking for exports: 
// Start export
await convex.mutation(api.system.updateProjectExportStatus, {
  projectId,
  status: "exporting",
  repoUrl,
});

// Complete export
await convex.mutation(api.system.updateProjectExportStatus, {
  projectId,
  status: "completed",
  repoUrl,
});
Status values:
  • exporting - Export in progress
  • completed - Export successful
  • failed - Export failed
  • cancelled - Export cancelled by user
Schema: convex/schema.ts:52

​
Rate Limiting

GitHub API has rate limits:
  • Authenticated requests: 5,000 requests/hour
  • Unauthenticated requests: 60 requests/hour
Polaris uses authenticated requests (via OAuth tokens) for higher limits.
Large repositories with many files may consume significant API quota. The import process makes one API call per file/directory.

​
Limitations

GitHub API limits file sizes:
  • Maximum file size: 100 MB
  • Recommended maximum: 10 MB
Large files should be stored using Git LFS (not currently supported).
Very large repositories (1000+ files) may take several minutes to import. Consider importing only specific directories if possible.
Binary files are imported but may not be editable in the IDE. They are stored in Convex storage.
Import creates a new project with current files only. Git history is not preserved. Export creates new commits, it doesn’t preserve original commit history.

​
Troubleshooting

Issue: API returns “GitHub not connected”Solution:
  1. Go to Account Settings
  2. Check if GitHub is listed under Connected Accounts
  3. If not, click “Connect GitHub” and authorize
  4. If listed but still failing, disconnect and reconnect
Issue: Import/export fails with authentication errorSolution: GitHub OAuth tokens can expire or be revoked. Reconnect your GitHub account:
  1. Go to Account Settings
  2. Disconnect GitHub
  3. Reconnect GitHub
Issue: Export fails with “repository not found”Solution:
  • Ensure the repository URL is correct
  • Check if the repository is private (requires proper access)
  • Enable “Create if not exists” to auto-create the repository
Issue: Import fails with “project limit reached”Solution: Free tier users are limited to 10 projects. Upgrade to Pro for unlimited projects:
  1. Go to Settings > Billing
  2. Click “Upgrade to Pro”

​
Security Considerations

GitHub tokens are stored securely in Stack Auth and never exposed to the client. All GitHub API operations happen server-side.
  • OAuth tokens are encrypted at rest
  • Tokens have limited scopes (only what’s necessary)
  • All API requests are authenticated
  • Rate limiting prevents abuse
  • Path validation prevents malicious file operations

​
Next Steps

Stack Auth

Learn about authentication and account management

Convex Database

Understand how project data is stored

Build docs developers (and LLMs) love

Get started for freeTalk to us