Linked repositories

Linked repositories are the code repositories that a Workspace searches. ctxpipe indexes each one for code search, and extracts its services, APIs, libraries, and their relationships into the Workspace repository as knowledge files.

A repository can be linked to many Workspaces. Each Workspace keeps its own index, so a search in one Workspace never returns the code of another.

Link repositories

Each linked repository is one source file in the Workspace repository, for example sources/github/<owner>/<name>.md. A pull request adds or removes the file. The change applies after you merge the pull request.

Open Add repositories

In the Workspace, open the Settings tab. Under Sources, choose Add repositories in the GitHub group.

Choose the repositories

Select GitHub: search the repositories that the ctxpipe GitHub App can see, and select one or more. Only an organization owner or admin can list them.
Paste URL: type the URL of a public repository on any git host, or of a public GitHub repository with no GitHub connection. See Plain git repositories.

Choose Open a pull request. One pull request can link up to 20 repositories.

Merge, then wait for indexing

Merge the pull request. Until then, the row shows Awaiting merge. After the merge, ctxpipe queues each repository for indexing.

To remove a repository, choose the unlink button on its row. ctxpipe opens a pull request that deletes the source file. After the merge, ctxpipe stops searching the repository and removes the knowledge that it extracted from it.

Pin a branch or tag

A source reads the default branch of the repository. To read another branch or a tag, add ref to the front matter with a pull request:

---
provider: github
connection: con_example
repository: acme/payments
ref: release
---

The payments API. Use it for questions about refunds and card tokens.

The body is an optional description of what the repository is for. People own the body, and ctxpipe never changes it. You can rename or move the file inside sources/github/. The pin stays with the repository.

Plain git repositories

ctxpipe can read a repository that needs no credential: a public repository on another git host, or a public GitHub repository. Use Paste URL, or add a source file under sources/git/ with a pull request:

---
provider: git
url: https://git.example.org/team/tools.git
---

ctxpipe checks the URL before it opens the pull request. On hosted ctxpipe, the URL must:

use https:// and the default port;
have a public domain name as its host, not an IP address or a name such as localhost, and resolve only to public addresses;
have no user name, password, query, or fragment.

ctxpipe does not support ssh (git@…, ssh://), git://, or file:// URLs, and does not follow a redirect. Use the exact clone URL. A repository that needs a credential works only on GitHub, through the GitHub App.

A self-hosted deployment can also read a git server inside your network. See Plain git repositories in the self-hosting configuration.

Indexing status

Status	Meaning
Pending	Linked, waiting for indexing.
Indexing	ctxpipe is building search and extracting knowledge. Answers can be incomplete.
Indexed	Search and extraction are done for the current commit.
Indexed with issues	Search works, but part of the index failed, usually code navigation for one language. The row shows the reason.

Indexing runs again when the linked branch or tag changes. Working now, in the Status group of Settings, shows the progress of each run.

What indexing builds

Code search: text, file, and symbol search over the linked branch.
Code navigation: definitions and references for the supported languages.
Extracted knowledge: services, APIs, libraries, infrastructure, and instructions such as AGENTS.md, skills, and ADRs. ctxpipe commits them to the Workspace repository as knowledge files with claims.

Extraction uses models on parts of the code. Treat extracted claims like other knowledge files: review them in git, and correct them when they are wrong.

Closed pull requests

For a linked GitHub repository, ctxpipe also mirrors its closed pull requests, merged or not, into github/pulls/ in the Workspace repository. When you link the repository, ctxpipe backfills up to 200 recent closed pull requests. After that, each pull request arrives when it closes. When you unlink, new pull requests stop. The files already mirrored stay. See GitHub connector.

On this page