How to Add an Existing Codebase to Agiloop

Created by Matthew Chartier, Modified on Wed, 1 Jul at 4:02 PM by Matthew Chartier

If you have an existing project on GitHub, GitLab, ADO or another git provider, you can bring it into Agiloop without starting from scratch. Agiloop will scan your repository, analyze the code, and automatically generate a functional and technical specification for the project — giving you a structured foundation to plan, build, and iterate on your product.

Overview

The “Analyze existing repo" flow connects your source control account, lets you select a repository, and then kicks off a background analysis job. When the job completes, your project will be populated with AI-generated specifications based on what Agiloop found in your code.

Step 1: Start the "Add project > Analyze existing repo" Flow

From your Agiloop dashboard or the projects menu, select the option to create a new project.
When prompted to choose how to set up your project, select Analyze existing repo (as opposed to starting a new project via the AI interview).

Step 2: Connect Your GitHub or GitLab Account

Agiloop will prompt you to authenticate via OAuth.

Choose either GitHub, GitLab, ADO or other as your provider.
You'll be redirected to the provider's authorization page. Review the requested permissions and approve access.
Once authorized, you'll be returned to Agiloop and your account will be linked.

Note: Agiloop requests only the permissions it needs to read your repositories. You can revoke access at any time through your git providers account settings under connected applications.

Step 3: Select a Repository

After connecting, Agiloop displays a list of repositories available on your account.

Browse or search for the repository you want to analyze.
Select the repository from the list.
Confirm your selection to begin the analysis.

Note: If you belong to multiple GitHub organizations or GitLab groups, make sure you've granted Agiloop access to the correct organization. You may need to update the OAuth permissions from your provider's settings if a repo isn't appearing.

Step 4: Codebase Analysis (Background Job)

Once you confirm the repository, Agiloop starts a background analysis job. This job scans your codebase and uses AI to interpret what the software does — identifying features, modules, functional and technical areas.

During this process, Agiloop:

Reads the structure and contents of your repository
Identifies distinct features and areas of functionality
Generates specifications including functional descriptions and technical context

This analysis runs automatically — you don't need to stay on the page or take any action.

Step 5: Monitor the Onboarding Job Progress

You can track the status of the analysis job directly within your project. Agiloop displays the current progress so you know where things stand.

While the job is running, you'll see a status indicator showing that the analysis is in progress.
You can navigate away from the project and return at any time — the job continues in the background.
If anything unexpected occurs during analysis, Agiloop will surface a status message within the project.

The time required depends on the size and complexity of your codebase. Most repositories complete within a few minutes.

Step 6: What to Expect When Analysis Completes

When the background job finishes, your project will be populated with the specifications, both functional and technical that Agiloop identified in your codebase.

From here, your project works exactly like any other Agiloop project. You can add features, invite team members, refine specs through the AI interview, queue features for implementation, and track progress on the Kanban board.

After Import: Next Steps

Once your codebase is imported and analyzed, consider these next steps:

Invite your team: Add team members to the project and assign roles (owner, admin, maintainer, or member) so everyone has the right level of access.
Refine specs via AI interview: For any feature where you want more detail, use the Invent tab to continue the AI-guided conversation and expand the specification.
Set up iteration goals: Head to the Iterate section to define product goals and review any technical debt Agiloop has flagged from the analysis.

How to Add an Existing Codebase to Agiloop

Related Articles