Repo Connect - Automatic Devbox Setup from a Github Repository

Automatic devbox setup from a github respository. Intelligent discovery of build commands, dependencies, and project structure

Start with the Runloop Quickstart to use the examples below.

Repo Connect currently supports TypeScript and Python repositories, with other languages coming soon. If you have suggestions or are interested in a specific language, please contact us at [e-mail].

Overview

Repo Connect automates the task of preparing a development environment to work with a code repository. Repo Connect automatically analyzes and understands your repository’s structure, dependencies, and build processes. The result is a Runloop Blueprint specifically configured to build, test, and run your code.

This saves time getting a Runloop Devbox up and running with your AI agent and code base. This is a huge reduction in time and effort for code analysis firms who interact with large numbers of repositories.

About Repo Connect

Repo Connect uses a GitHub token to securely access your repository and employs a combination of semantic analysis and AI agents to intelligently discover:

• Setup and build commands
• Test execution procedures
• Package managers and dependency installation
• Environment initialization requirements
• Available project commands and scripts

After a successful analysis, Repo Connect generates a Runloop Blueprint that includes all of the setup and configuration needed for working with your code. Devboxes created from the Repo Connect blueprint are immediately ready for your AI agent to operate on your code, enabling features like running specific code paths, tracing and debugging, and making informed changes.

Creating a Repo Connect Analysis

Basic Repository Analysis

For a simple way to add a single repo, you can add repo information on Repo Connect page of the Runloop Dashboard.

The Runloop SDKs provide tools for quickly using Repo Connect on thousands of repos. The ‘repositories.create’ function initiates analysis of your repository, automatically discovering build tools, dependencies, and setup requirements.

Python

repository_connection_view = await runloop.api.repositories.create(
    name="simple-todos",
    owner="runloopai",
)
print(repository_connection_view.id)

Understanding Analysis Results

When Repo Connect completes its analysis, you’ll receive detailed information about your repository’s structure and requirements:

Successful Analysis

A successful analysis provides:

• Extracted Tools: Discovered commands for building, testing, and running your project
• Package Manager: Identified dependency management system (npm, pip, maven, etc.)
• Setup Commands: Environment initialization and workspace preparation steps
• Blueprint: A reusable configuration for future Devbox instances

Partial Analysis

If Repo Connect cannot fully analyze your repository, it generates a partial inspection with discovered information pre-filled. You can then edit and complete the missing details to achieve a working state for your AI agent.

The analysis results follow this structure:

interface RepositoryVersionDetails {
  analyzed_at: number;
  commit_sha: string;
  extracted_tools: {
    commands: Record<string, string>;
    package_manager: string;
  };
  repository_setup_details: {
    blueprint_id: string;
    env_initialization_command: string;
    workspace_setup: Array<string>;
  };
  status: 'inspecting' | 'inspection_failed' | 'success';
}

Using Analyzed Repositories

Once Repo Connect has analyzed your repository, you can create Devboxes that are immediately ready for AI agent interaction:

Python

inspection = await runloop.api.repositories.get_inspection(id='REPO_CONNECT_ID')
if inspection.status == "image_build_success":
  dbx = await runloop.devboxes.create(
    name='devbox-name',
    blueprint_id=inspection.blueprint_id
  )
  print(dbx.id)
  

Your AI agent can now:

• Execute discovered build and test commands
• Navigate and understand your codebase structure
• Make informed changes based on project conventions
• Debug and trace execution paths
• Install and manage dependencies automatically

Containerized services within a Repo Connect

Repositories often have dependencies on containerized services that run alongside your agent, codebase, or devbox. Our repository connection process surfaces any service declared in the repository’s Github Actions workflow files as a part of the final blueprint. You can confirm this by querying the blueprint and before launching a devbox with the available services initialized.

You will need:

• blueprint_id from a Repo Connect Inspection to confirm the available services
• blueprint_id or repo_connection_id to launch a devbox with the services

The following example shows how to launch a devbox from Repo Connection rpc_123456789 that’s created blueprint with id bpt_123456789 with the postgres service available.

The required_services when launching a devbox will be used to determine which services to start and each service must match one of the name elements in the containerized_services list otherwise the devbox will fail to start.

"containerized_services": [
  {
    "name": "postgres",
  },
  ...
]

Python

blueprint = runloop.blueprint.from_id(blueprint_id='bpt_123456789')
devbox = await blueprint.create_devbox(
  name='devbox-name',
  repo_connection_id='rpc_123456789',
  launch_parameters={ "required_services": ["postgres"] }
)

Refreshing Repo Connect

As your repository evolves, you can refresh the Repo Connect analysis to capture new changes, dependencies, or build processes:

Python

await runloop.api.repositories.refresh(id='REPO_CONNECT_ID')

This allows you to see the progression of your development environment and ensure your AI agent always has the most current understanding of your project.

Best Practices

Repository Preparation

1. Standard Build Files: Use conventional build files (package.json, requirements.txt, Makefile) when possible
2. Environment Files: Include .env.example or similar files to help identify required environment variables. Repo Connect will ask for secret values if required

Token Security

1. Use GitHub tokens with appropriate repository access permissions
2. Regularly rotate your tokens and update Repo Connect configurations
3. Monitor token usage and revoke access if needed

Blueprint Management

1. Review generated blueprints to ensure they capture your project’s requirements accurately
2. Version your blueprints alongside your code to maintain consistency
3. Test blueprints with fresh Devbox instances to verify completeness

Repo Connect works best with repositories that follow standard project conventions and include clear build instructions. For complex or non-standard setups, review the partial analysis results and add any missing configuration details.