# Linked repositories (https://docs.ctxpipe.ai/docs/workspaces/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.

<Steps>
  <Step>
    ### Open Add repositories

    In the Workspace, open the **Settings** tab. Under **Sources**, choose
    **Add repositories** in the **GitHub** group.
  </Step>

  <Step>
    ### 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](#plain-git-repositories).

    Choose **Open a pull request**. One pull request can link up to 20
    repositories.
  </Step>

  <Step>
    ### 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.
  </Step>
</Steps>

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:

```markdown
---
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:

```markdown
---
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](/docs/self-hosting/configuration#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](/docs/connections/source-connectors/github).