Skip to main content
A source is any codebase you want the team to work on: a GitHub repository, an Azure DevOps repository, or a local folder on your machine. Once you connect a source to a workspace, Orkestral reads it, maps it, and gives every agent (CEO, Tech Lead, Code Reviewer, and the specialists) full context to plan and execute work. This guide walks you through every way to add a source, explains what mapping does, and shows how Orkestral stays aware of git the whole time.
Sources belong to a workspace. Make sure the workspace you want is active before you start. The dialog reads the active workspace automatically.

​
What you can connect

GitHub repository

Pick from the repos your GitHub account can see. Orkestral clones it locally so agents have the real files.

Azure DevOps repository

Connect your Azure DevOps account once, then choose any repo your account can access.

Local folder

Point Orkestral at a folder already on your disk. It scans for git repos inside and lets you add several at once.

​
Open the add source dialog

1

Make sure the right workspace is active

The source you add lands in whatever workspace is active. Switch workspaces from the sidebar if needed. Switching workspaces also changes the accent color, which is a quick visual confirmation you are in the right place.
2

Trigger Add source

Open the Add source dialog from the sidebar or wherever your workspace exposes it. The dialog is global, so you can open it from anywhere in the app.
3

Pick a tab

Choose GitHub, Azure, or Folder at the top of the dialog. The rest of this guide has one section per tab.

​
Connect a GitHub repository

1

Open the GitHub tab

The dialog loads the list of repositories your GitHub account can access. If the list is empty or errors out, your GitHub connection is missing or expired, so reconnect GitHub first.
2

Search and select a repo

Use the search box to filter by full name (for example your-org/your-repo). Click a repo to select it. The list shows up to 50 matches, so narrow the search if you do not see yours.
3

Set the label and role

  • Label is the friendly name shown across the app. It defaults to the repo name, and you can change it.
  • Role tells the team how to treat this source (for example Frontend or Backend). Roles use the standard role set. Leaving it empty is fine.
4

Decide on analysis

Leave Analyze after adding checked to let Orkestral map the code and propose a team right away. See What mapping does below.
5

Add the source

Click Add. Orkestral clones the repo locally and registers it in the workspace. The first source you add becomes the primary source automatically.
Private repos clone over HTTPS using an ephemeral auth header. The token is used only for the network call and is never written into .git/config, so the stored remote URL stays clean.

​
Connect an Azure DevOps repository

1

Connect your Azure account (first time only)

If no Azure account is linked yet, the tab shows a Connect button. Click it to start a device-code sign-in. Orkestral opens the verification page in your browser. Enter the code, approve access, and the dialog detects the approval automatically.
2

Search and select a repo

Once connected, the tab lists the repositories your Azure account can reach. Filter by full name and click the one you want. Each row shows the remote URL so you can confirm you picked the right project.
3

Set the label and role

Same as GitHub: the Label defaults to the repo name and the Role is optional.
4

Add the source

Click Add. Orkestral registers the Azure repo just like a GitHub one, and the first source in the workspace becomes primary.
If the sign-in window sits too long, the device flow expires and you will see an error. Just click Connect again to restart it.

​
Connect a local folder

The folder tab is the most flexible option, because Orkestral scans what you point it at and helps you add nested repos in one pass.
1

Choose a folder

Type or paste an absolute path, or click Choose to open the native folder picker. The label defaults to the folder name once you pick one.
2

Set an initial label and role

Fill in a Label and an optional Role for the top folder. You can still adjust these per item in the next step if a scan finds nested repos.
3

Let Orkestral scan

Click Add to scan the folder. Two things can happen:
If the folder is itself a git repo, or it contains no git repos inside, Orkestral adds it as a single source and closes the dialog.
4

Review the selection (when repos are found)

Each row shows the path and an icon: a branch icon for a git repo, a folder icon with a local folder badge for the parent. For every checked item you can edit its Label and Role independently. Uncheck anything you do not want.
5

Add the selected items

Click Add selected. Orkestral creates each checked item as its own source. The first one becomes primary if the workspace had no sources yet, and the team proposal (if enabled) runs once at the end rather than once per repo.
If the multi-add fails partway through, some sources may already exist. Orkestral deduplicates by path, so re-submitting will not create duplicates. The dialog stays open so you can retry the rest.

​
What mapping does

Mapping (also called analysis or indexing) is what turns a raw codebase into context the team can reason about. When Analyze after adding is checked, two things run after the source is created.
Orkestral reads the source and builds an understanding of its structure, stack, and conventions. This is what lets a premium model PLAN accurately and what lets the FORGE (the bundled local model) EXECUTE edits that fit your codebase. Knowledge coverage is tracked per workspace so you can see what has been mapped.
After mapping, Orkestral proposes a team tailored to what it found, so you can hire the specialists the codebase actually needs. When you add several folders at once, this proposal runs a single time on the last item, so you are not flooded with one team proposal per repo.
You can leave Analyze after adding unchecked if you only want to register the source now and map it later. Mapping is what gives agents their context, so run it before you expect high-quality plans.

​
Git awareness

For any source that is a git repo, Orkestral shells out to the git CLI already on your machine. That means it behaves exactly like your terminal and works the same on macOS, Linux, and Windows. Here is what it tracks and does.

Status

Current branch, upstream, how many commits you are ahead or behind, and every changed file (staged, unstaged, and untracked). New files inside a new folder each show up individually.

Diffs

Per-file diffs with generous context, including untracked files rendered as fresh additions so nothing is invisible in the review panel.

Branches

List local and remote branches with their last commit, check out a branch, or create a new one from any base.

Commit and sync

Stage, unstage, discard, commit, then push, pull, or fetch. Network operations on private HTTPS repos use the same ephemeral auth header pattern as cloning.
Errors are translated into plain guidance. A rejected push tells you to pull first, an up-to-date push tells you there is nothing to send, and an auth failure points you at configuring your credentials.

​
After you connect

Brief the CEO

Open a chat and describe what you want. The CEO orchestrator reads the mapped source, plans, and delegates to specialists.

Track the work

Plans become issues and epics you can follow as the team executes changes locally through the Fast Apply engine.

Add more sources

A workspace can hold many sources. Repeat this flow to connect every repo and folder the team should see.

Set roles deliberately

Roles shape how agents reason about each source. Revisit them as your project grows so the right specialist owns the right code.