Skip to main content

Repository Import Guide

Import your existing GitHub repositories to create intelligent, context-aware build plans. This guide will help you successfully import repositories and troubleshoot common issues.

Overview​

Repository Import allows you to:

  • Connect your GitHub account with secure OAuth
  • Select and scan repositories for automated analysis
  • Generate context-aware build plans that understand your existing codebase
  • Continue conversations with persistent state across page reloads

Step-by-Step Import Process​

1. Start Repository Import​

  1. Navigate to Build Plans in your dashboard
  2. Click "Create New Project"
  3. Select "Import from Repository"
  4. You'll be redirected to the import wizard

2. Connect GitHub Account​

First Time Setup:

  1. Click "Connect GitHub"
  2. You'll be redirected to GitHub OAuth
  3. Review and approve the permissions:
    • ✅ Read access to public and private repositories
    • ✅ User profile information
    • ❌ No write access - we can't modify your code
  4. You'll be redirected back to Buildable with a success message

Permission Details:

  • We only request read-only access
  • We can't modify, delete, or push to your repositories
  • You can revoke access anytime in your GitHub settings
  • We don't store your source code, only project metadata

3. Select Repository​

  1. Choose repository type using the dropdown filter:
    • All Repositories - Shows both personal and organization repos (default)
    • Personal Only - Only repositories you own
    • Organizations - Only organization repositories you're a member of
  2. Browse your repositories in the list
  3. Use search to find specific repositories by name, description, or language
  4. Sort options:
    • Recent - Recently updated repositories (default)
    • Name - Alphabetical order
    • Created - Recently created repositories

Repository Requirements:

  • Must be accessible with your GitHub permissions
  • Maximum size: 100MB (for optimal scanning performance)
  • Supports all major programming languages

Organization Repository Access:

  • Repositories from organizations you're a member of are now included
  • Organization name is displayed as a badge next to repository name
  • Same scanning and analysis capabilities as personal repositories

4. Repository Scanning​

Once you select a repository:

  1. Scanning starts automatically - No additional action needed
  2. Real-time progress shown with scanning status
  3. Analysis includes:
    • 📁 File structure and organization patterns
    • 🔧 Technology stack detection (languages, frameworks, databases)
    • ✨ Existing features identification
    • 🏗️ Architecture patterns analysis
    • 📊 Project statistics (file counts, sizes, complexity)

Scanning Timeline:

  • Small projects (< 50 files): 10-30 seconds
  • Medium projects (50-200 files): 30-60 seconds
  • Large projects (200+ files): 1-3 minutes

5. Context-Aware Conversation​

After scanning completes:

  1. Automatic navigation to conversation page
  2. Pre-populated project details from repository analysis
  3. Intelligent initial message that references your specific codebase
  4. Ready to plan enhancements and new features

Understanding Scan Results​

Technology Detection​

The scanner identifies:

Languages & Frameworks:

  • Primary language (TypeScript, JavaScript, Python, etc.)
  • Framework detection (React, Next.js, Django, Express, etc.)
  • Build tools (Webpack, Vite, etc.)

Dependencies & Infrastructure:

  • Package.json analysis for Node.js projects
  • Requirements.txt for Python projects
  • Database technologies (PostgreSQL, MongoDB, etc.)
  • Deployment configurations (Docker, Vercel, etc.)

Example Scan Summary:

Technologies Found: TypeScript, React, Next.js, Supabase
Features Detected: Authentication, User Management, Dashboard
Project Structure: Component-based architecture, API routes
File Types: 45 .ts files, 29 .tsx files, 3 .css files

Feature Recognition​

Our AI identifies existing features by analyzing:

  • Component names and structure
  • API endpoints and routes
  • Database schema patterns
  • Configuration files
  • Documentation and comments

Common Feature Categories:

  • 🔐 Authentication - Login, signup, session management
  • 👥 User Management - Profiles, settings, permissions
  • 📊 Analytics - Dashboards, metrics, reporting
  • 💰 Payments - Billing, subscriptions, transactions
  • 📧 Communication - Email, notifications, messaging
  • 🛠️ Admin Tools - Management interfaces, configurations

Architecture Analysis​

The scanner understands:

  • Component organization patterns
  • State management approaches
  • API design conventions
  • Data flow architecture
  • Testing strategies
  • Error handling patterns

Troubleshooting Common Issues​

GitHub Connection Issues​

Problem: "GitHub connection failed" error

Possible Causes & Solutions:

  1. OAuth popup blocked

    • Enable popups for bldbl.dev in your browser
    • Try again with popup blocker disabled

  2. Permission denied during OAuth

    • Ensure you click "Authorize" on the GitHub page
    • Check if your organization requires admin approval
    • Try connecting with a personal repository first

  3. Network or timeout issues

    • Check your internet connection
    • Try refreshing the page and reconnecting
    • Clear browser cache and cookies

Verification Steps:

# Check if connection worked
1. Look for "GitHub Connected" success message
2. Verify you can see repositories in the list
3. Check for your username in the top-right corner

Repository Scanning Problems​

Problem: Scan gets stuck in "Scanning..." status

Possible Causes & Solutions:

  1. Large repository size

    • Repository may exceed 100MB limit
    • Try scanning a smaller repository first
    • Contact support for enterprise scanning options

  2. Network timeout

    • Refresh the page and try again
    • Check internet connection stability
    • Wait a few minutes and retry

  3. Repository access issues

    • Verify you have read access to the repository
    • Check if repository is private and permissions are correct
    • Try with a public repository to test

Retry Process:

  1. Click the "Retry Scan" button if available
  2. Or go back and select the repository again
  3. Wait for the full scanning process to complete

Problem: "No files found" or incomplete scan results

Possible Causes & Solutions:

  1. Empty or minimal repository

    • Repository has very few files to analyze
    • Try with a repository that has more substantial code

  2. Unsupported file types

    • Scanner focuses on code files (.js, .ts, .py, etc.)
    • Documentation-only repositories may have limited results

  3. Access restrictions

    • Some files may be inaccessible due to GitHub permissions
    • Try with a repository you fully own

Conversation Issues​

Problem: Conversation starts from scratch after page reload

Solutions:

  1. Check URL parameters

    • Ensure the snapshot=xyz parameter is in the URL
    • If missing, go back to repository selection

  2. Clear browser data

    • Clear localStorage for bldbl.dev
    • Refresh and try the import process again

  3. Repository context mismatch

    • If you switched repositories, conversation resets automatically
    • This is expected behavior for security

Problem: Repository context not showing in conversation

Solutions:

  1. Verify scan completion

    • Ensure scanning finished successfully
    • Check that scan results show technologies and features

  2. Refresh conversation page

    • Reload the page to fetch latest repository data
    • Look for the blue "Repository context loaded" indicator

  3. Check snapshot validity

    • Scan data may have expired (7 days)
    • Re-scan the repository if needed

Permission and Access Issues​

Problem: "Repository not found" or "Access denied" errors

Solutions:

  1. Verify repository access

    • Check you can access the repository on GitHub
    • Ensure repository still exists and wasn't deleted

  2. Update GitHub permissions

    • Go to GitHub Settings → Applications → Buildable
    • Ensure proper repository access is granted

  3. Organization repositories

    • Organization admin may need to approve access
    • Try with personal repositories first

Problem: "GitHub token expired" error

Solutions:

  1. Reconnect GitHub account

    • Go through the GitHub connection process again
    • This will refresh your access token

  2. Check token expiration

    • GitHub tokens expire after a certain period
    • Regular reconnection may be required

Best Practices​

Choosing Repositories for Import​

Ideal Repositories:

  • 🎯 Active projects you're currently enhancing
  • 📊 Substantial codebases (50+ files) for better analysis
  • 🏗️ Well-structured projects with clear patterns
  • 🔧 Modern tech stacks for best AI understanding

Less Ideal:

  • 📚 Documentation-only repositories
  • 🗄️ Legacy code without clear structure
  • 🔬 Experimental or prototype repositories
  • 📦 Fork repositories without significant changes

Optimizing Scan Results​

Repository Preparation:

  1. Update README with current project description
  2. Ensure package.json (for Node.js) or equivalent is up to date
  3. Clean up unused files to improve signal-to-noise ratio
  4. Use descriptive commit messages for better context

For Better Feature Detection:

  • Use clear component and file names
  • Include API documentation or comments
  • Maintain consistent project structure
  • Keep dependencies updated

Conversation Tips​

Starting the Conversation:

  • ✅ "I want to add user roles to my existing auth system"
  • ✅ "Help me plan a notification feature for my Next.js app"
  • ✅ "What's the best way to add payments to my SaaS?"

Avoid Generic Questions:

  • ❌ "Help me code"
  • ❌ "What should I build?"
  • ❌ "Fix my app"

Reference Your Codebase:

  • "Based on my existing user management..."
  • "Given my current API structure..."
  • "To integrate with my Supabase setup..."

Advanced Features​

Multi-Repository Planning​

Coming Soon:

  • Import multiple related repositories
  • Understand microservice dependencies
  • Plan features across service boundaries

Incremental Updates​

Future Enhancement:

  • Webhook integration for automatic updates
  • Detection of new features added manually
  • Smart re-scanning of changed files

Team Collaboration​

Planned Features:

  • Share imported repository context with team members
  • Collaborative planning sessions
  • Team-wide repository access management

Getting Help​

Self-Service Resources​

  1. API Documentation - Technical integration details
  2. Integration Guides - Integrations overview
  3. FAQ - Common questions and answers

Contact Support​

When to Contact Support:

  • Repository import fails repeatedly
  • Large repository scanning needs (>100MB)
  • Organization-specific permission issues
  • Enterprise deployment questions

How to Contact:

Information to Include:

  • Repository URL (if public) or name/size if private
  • Error messages or screenshots
  • Browser and version
  • Steps to reproduce the issue

Quick Reference​

Import Checklist​

  • GitHub account connected successfully
  • Repository appears in the list
  • Repository size is under 100MB
  • Scan completes with technology detection
  • Conversation loads with repository context
  • Can ask questions about existing codebase

Common URLs​

  • Import Start: /onboarding
  • Repository Selection: /onboarding/import
  • Conversation: /onboarding/conversation?snapshot={id}
  • Dashboard: /dashboard

Scan Status Meanings​

  • pending - Scan queued, will start shortly
  • scanning - Actively analyzing repository
  • completed - Successfully finished, ready for conversation
  • failed - Error occurred, check error message and retry

Ready to import your first repository? Start here →