Repositories and GitHub

Connecting your GitHub repositories lets DevSpec read your code and build a searchable map of it. Dev then answers from how your product really works, your agents start with the right context, and your commits and pull requests link back to the work they belong to. DevSpec works with GitHub. Your organization connects GitHub once, and each project then chooses which of the allowed repositories it tracks.

DevSpec reads your code, pull requests and GitHub checks so you can connect repository activity to the work it belongs to. It can also show the destination branch's rules; Administration read gives it access to classic branch-protection details without allowing it to change them. You review and merge pull requests on GitHub. DevSpec does not commit code for you. Your code is only used to run DevSpec for you. It's never sold and never used to train AI, and removing a repository deletes everything DevSpec read from it. See the privacy policy for how we handle your data.

Repositories are managed in Project settings → Repositories, or on the first step of a new project's Project setup.

Give your organization access to GitHub

GitHub access belongs to your DevSpec organization, not to one person. Every project the organization owns can use the repositories you allow, and access keeps working when people join or leave.

Organization Owners and Admins set it up:

1. Open Settings → Organization → Connections. The GitHub access section shows whether your organization is connected.
2. Click Connect GitHub. GitHub opens in a new tab, and the DevSpec page shows "Finish on GitHub, then come back. This page updates by itself."
3. On GitHub, choose the account or GitHub organization to install on, and which repositories to allow:
   • All repositories: new repositories show up in DevSpec automatically.
   • Only select repositories: you grant each new repository on GitHub as you need it.
4. GitHub asks you to authorize DevSpec. This is how DevSpec confirms who you are on GitHub before it connects anything; it only reads who you are and keeps no access to your account.
5. Return to DevSpec. The section shows the GitHub account and which repositories are allowed.

GitHub lists exactly what DevSpec is asking for on its install screen. If you aren't an owner of the GitHub organization, GitHub lets you request the install instead, and DevSpec tells you the request went to a GitHub owner. Once an owner approves it on GitHub, DevSpec connects it to your organization by itself and sends you a notification, and you can carry on choosing repositories.

You can also start the same trip from a project's repository picker or from Project setup. Once connected, the picker shows which GitHub account is connected. Use Change repositories on GitHub, there or on the Connections page, to change which repositories are allowed.

Organization Members can see the GitHub access status but not change it. Guests don't see organization settings.

Disconnect GitHub

An Owner or Admin can remove DevSpec's access with Disconnect GitHub, in the GitHub access section or next to the connected account in a project's repository picker, including during Project setup. Before anything changes, DevSpec names the GitHub account and says how many repositories in how many projects stop updating, and asks you to confirm. DevSpec then uninstalls its app from that account on GitHub.

The repositories stay in their projects, and their Maintainers are told they've stopped updating. Uninstalling the app from GitHub's own settings has the same effect.

To resume, connect that GitHub account again from Settings → Organization → Connections and include the repositories you want DevSpec to access. If you only removed a repository from the allowed list, add it back with Change repositories on GitHub. DevSpec reconnects existing tracked repositories when it can verify access, keeping their project history. You don't need to remove and add them again or make a test commit. If GitHub needs an owner's approval, recovery waits for that approval. If GitHub is temporarily unavailable, DevSpec retries automatically.

If your GitHub account is connected to another organization

A GitHub account can be connected to only one DevSpec organization at a time. If you choose one that another DevSpec organization already holds, DevSpec tells you it is already connected to another DevSpec organization and leaves that organization's connection untouched. To move it here, an Owner or Admin in the organization holding it can use Disconnect GitHub on Settings → Organization → Connections, or a GitHub owner can uninstall the app on GitHub; after that, you can connect it here. If you installed on the wrong account, choose Install on a different GitHub account.

Moving a GitHub account's connection affects every repository using that connection in the other DevSpec organization, not just one repository. It does not move any DevSpec projects or their history. Don't disconnect a shared connection just to repair a single repository without checking that impact.

If a repository is renamed or moved

DevSpec keeps a repository's existing project and history when it can verify that it is the same repository. Renaming it does not require you to remove and add it again.

If it moves to another GitHub account, that account must be connected to your DevSpec organization and include the repository in its allowed access. Use Fix on the repository to check access or connect the destination account. A GitHub owner may need to approve access. DevSpec reconnects automatically once it can verify access; your next normal push confirms delivery, with no test commit needed.

If DevSpec cannot reach the moved repository, the repository card shows that access was lost so you can reconnect it. If the destination GitHub account belongs to another DevSpec organization's connection, recovery stays blocked: your existing project and history do not move with the repository.

Link your GitHub account

Link the GitHub account you use, so pull requests and commits from it show as yours in your projects. Open Settings → Profile, and under Your GitHub account choose Link GitHub account. GitHub confirms it's you; DevSpec keeps no access to your account. When you connect an agent to a project with GitHub repositories, the agent gives you the same link if you haven't linked one yet. Installing the app, or requesting it, links your account too.

A GitHub account is linked to one person at a time. If someone else confirms on GitHub that they control an account linked to you, it moves to them and you're told. Your name is only shown to people in projects you're a member of; anyone else sees the GitHub username. To stop showing your name on an account's work, choose Unlink.

If you can't install the app yourself

The app is the only way DevSpec connects to GitHub. It works for repositories under your own GitHub account or a GitHub organization's, and installing it on a GitHub organization takes one of that organization's owners. If you aren't an owner, request the install on GitHub's install screen and ask an owner to approve it, as described in "Give your organization access to GitHub" above.

Add a repository to a project

Project Maintainers add and remove repositories.

1. Open Project settings → Repositories and click Add repository. The Add or remove repositories dialog lists the repositories your organization has allowed. Repositories this project already tracks are marked.
2. Click Add beside a repository.
3. Choose its Tracking branch (see "Choose a tracking branch" below) and click Save.

DevSpec then reads the repository and builds a search index of its code. The card shows progress as it goes, and the project's Overview shows a Reading your code card during the first index. See Code indexing.

A project can track several repositories, such as a frontend, a backend and shared libraries, and Dev searches across all of them. Adding a repository to one project doesn't add it to your other projects.

Choose a tracking branch

Every repository in a project has one Tracking branch: the branch DevSpec indexes, reviews, and sends agents to. It's the only setting a repository must have.

• It's pre-filled with the repository's default branch. You can pick another; the branch must already exist on GitHub.
• With the default settings in Project settings → Agent rules, an agent merges its finished work into the tracking branch and pushes. So out of the box, agent work lands on your default branch.
• DevSpec recommends a branch your team doesn't push to directly, such as staging or develop, so agent work never collides with yours.
• Dev searches the tracking branch unless you ask about another branch, and a deployment target for this repository follows it too.

To change it, click the branch beside Tracking branch on the repository card and pick a branch. See Working with your agents for the push and merge settings.

Track more branches

The card's branches section lists the tracked branches and the branches Available from GitHub. Click Track beside a branch to index it too; DevSpec then keeps it current as you push, and Dev can search it by name. Each tracked branch has its own Reindex this branch and Disable tracking controls.

Read a repository card

Each tracked repository has a card in Project settings → Repositories. It shows:

• the file count, when it was last indexed, and how many commits it's behind GitHub
• a status badge while it's cloning or indexing, and a progress bar with an estimated time remaining
• the Tracking branch, Repo type and Delivery signal
• whether DevSpec is receiving the repository's pushes (see "If pushes aren't arriving" below)

Repo type records what the repository is (web app, API, mobile app, library and so on). Delivery signal records what tells DevSpec the repository's work is ready to test. Only Hosted deployment is tracked automatically, once you connect Vercel or Coolify under Deployment targets; the other choices record how you ship. See Delivery.

Maintainers get these icon buttons on the card (hover to see the name):

If the connection to GitHub needs attention, the card shows Connection needs attention.

If pushes aren't arriving

There's nothing to test when you add a repository: your first real push confirms that DevSpec is receiving them. Under each repository card, a status line then shows:

• Receiving your pushes, with the time of the last one.
• Pushes aren't arriving · Fix, if GitHub records pushes that never reach DevSpec. DevSpec checks for this regularly and alerts the project's Maintainers when it happens.

Click Fix and DevSpec tells you the cause and the one thing to do about it:

• Check access on GitHub or Restore access on GitHub: the DevSpec app has lost access to the repository, or been suspended, on GitHub. Fix it there, then use Test it now.
• Test it later: the problem is on DevSpec's side, and there's nothing for you to change.

While pushes aren't arriving, DevSpec still checks each repository for changes periodically in the background, so new commits show up late rather than never.

When GitHub asks for updated permissions

The repository page tells you whether a permission update is available or existing access needs attention, and names the affected features. Choose Review permissions on GitHub and ask a GitHub administrator to approve the update. Features with sufficient access keep working.

The GitHub app requests Checks, Commit statuses, Pull requests, Contents and Workflows write permissions as well as read access. Review the full permission list on GitHub before connecting. These grants do not change where you review and merge work: those actions stay on GitHub.

Permission to administer a project in DevSpec does not give you permission to approve an installation change on GitHub.

See pull requests

DevSpec keeps your pull requests up to date from GitHub on its own. Wherever a pull request is mentioned, in a session, on a task or on a deployment, click it to open it in DevSpec. Pull requests that are open and waiting to merge are listed on Delivery, under Waiting to land.

Open a pull-request reference in DevSpec to see its GitHub reviews, checks, delivery, linked tasks and linked knowledge. Work approval and verification are shown separately; proposed document changes link to Review.

GitHub rules shows the destination branch's active rules and available branch-protection details. View rules on GitHub opens the full settings. Use Discuss to talk through the pull request, or View on GitHub for its diff and review conversation.

In a session, Dev can read a pull request by its number, including the work it delivered. DevSpec never approves, merges or blocks a pull request; you do that on GitHub.

Remove a repository

A Maintainer removes a repository with Remove repository on its card, then Remove repo to confirm. The repository is untracked from this project: indexing stops, and the code DevSpec read from it is deleted. On a large repository this can take a few minutes. You can add it back later; it's indexed again from scratch.

Removing a repository doesn't revoke DevSpec's access on GitHub. To change which repositories DevSpec can reach, use Change repositories on GitHub on Settings → Organization → Connections. To remove its access altogether, use Disconnect GitHub there.

What DevSpec can do with your code

• Every member of the project can read code tracked into it, through Dev in sessions. Keep that in mind before you track a private repository into a project with many members.
• DevSpec never commits code of its own. Changes come from your agent or from you, using your own git credentials. DevSpec shows GitHub reviews, checks and branch rules; review and merging stay on GitHub.
• DevSpec reads your files, commits and pull requests, and hears about your pushes through its GitHub app. It doesn't add webhooks to your repositories.
• Organization access reaches only the repositories you allowed on GitHub.
• The first full index of your organization's first repository is free. After that, indexing is a background charge on your organization's balance. See Code indexing.