Skip to content

Knowledge base from GitHub or GitLab repos ​

Instead of pushing documents by hand with ph kb push, you can attach a GitHub or GitLab repository to the knowledge base. Tara reads the README, docs, and ADRs, keeps them up to date, and lets you and your agents search them with source citations. Private repositories stay private: each person sees a private repository's documents only if their own GitHub or GitLab account can read it.

You need an organization that has installed the PhillipCLI GitHub App (see Connect GitHub) or connected a GitLab group (see Connect GitLab). For GitLab, only repositories inside the connected group can be attached, public or private. Attaching and removing repositories is for Owners and Admins. Reading and searching is for every member.

Attach a repository ​

In the Portal, open Knowledge, go to Repository sources, and pick a repository from the list: the repositories the GitHub App can see and the projects of the GitLab group appear together. From the terminal, signed in with ph login:

Each source shows its provider, visibility, document count and last sync; the form below attaches another repository.
bash
ph kb source add acme/shop                         # README, docs, and ADRs (the default patterns)
ph kb source add acme/shop --include 'docs/**' --include 'handbook/*.md'
ph kb source add https://gitlab.com/acme/platform/shop   # a GitLab project (use its URL; subgroups are fine)
ph kb sources                                      # attached repositories and their sync status

For GitLab, ph kb source sync and ph kb source remove take the same project URL, or the full path when it has three or more segments (acme/platform/shop). The host must be the one of your GitLab connection.

The first sync starts right away. You can watch the status with ph kb sources.

What gets synced ​

Tara reads Markdown and plain-text files (.md, .markdown, .mdx, .txt, and README files) that match the include patterns. Without --include, the patterns are README*, docs/**, doc/**, adr/**, **/docs/**, **/adr/**, and **/README*.

In a pattern, * stays inside one folder level, ** crosses folders, and a pattern without a / matches only the repository root. Tara never reads node_modules, vendor, dist, build, or .git. A repository can contribute up to 1000 files and 64 MiB, and each file can be up to 2 MiB.

Every repository becomes one space, named gh-<owner>-<repo> for GitHub (for example gh-acme-shop) and gl-<group>-<subgroup>-<project> for GitLab. The space is read-only for people: to change a document, change it in the repository.

How it stays up to date ​

  • On push. A push to the default branch triggers a sync through the GitHub App's webhook. This needs the Push and Repository events on the app (the registration page lists them). On GitLab, set up the connection's webhook by hand with Push events ticked. Tara syncs that exact commit, and only for pushes to the default branch of a project inside the group. Deleting a project on GitLab marks its source as failed.
  • Periodically. Tara also syncs every hour by default, which catches anything a webhook missed. This is the only trigger on GitLab until you add the webhook.
  • Sync now. Run ph kb source sync acme/shop (add --wait to wait until it finishes), or press Sync now in the Portal.

Only files whose content changed are processed again, and files that left the repository are removed. If a sync fails, the previous documents stay searchable and the error shows next to the repository.

Who can see what ​

  • Nobody outside the organization that attached the repository.
  • For a public repository, every member of the organization.
  • For a private repository, only members whose linked GitHub account has at least read access to that repository. Tara asks GitHub through the app and remembers the answer for 10 minutes. If you lose access on GitHub, you lose it here within 10 minutes.
  • On GitLab the rule is the same. A member must have signed in to Tara with GitLab on the connection's host, and GitLab must report them as a member of the project (directly or through the group) with the Reporter role or higher. Guests can't read code in a private project, so they don't count. GitLab's internal visibility is treated as private, so a person who isn't a member is refused even if GitLab would let them read it. Tara asks GitLab with the connection's credential, remembers the answer for 10 minutes, and picks up a change of visibility at the next hourly sync.

When Tara can't be sure, it says no. A member with no linked GitHub or GitLab account, a repository outside the installation or group, a suspended installation, a GitLab connection that needs reconnecting, or an error from the host all mean no access to a private repository's documents. Tara doesn't store anyone's GitHub or GitLab token.

To link your account, sign in with GitHub or GitLab or link it in your account settings.

Search from Claude Code ​

The documents are in the same knowledge base, so the kit-knowledge kit searches them with the same permissions as the Portal. Install it once:

bash
ph tara add kit-knowledge

Then the agent can call search, get_document, and list_spaces in the session. Add --space gh-acme-shop to ph kb search to limit a terminal search to one repository. Citations point back to the file on GitHub or GitLab at the synced commit.

Commands ​

CommandWhat it does
ph kb sourcesList attached repositories with their sync status
ph kb source add <owner/repo or GitLab URL> [--include <glob>]…Attach a repository
ph kb source sync <owner/repo> [--wait]Sync now
ph kb source remove <owner/repo>Detach the repository and delete its documents

All of them accept --json. The full list is in the ph kb reference.

Limits ​

  • Tara downloads each repository as an archive of up to 256 MiB compressed. A larger repository fails to sync. Narrow it with --include, or split what you need into a smaller repository.
  • Text only, no PDF, as with the rest of the knowledge base.
  • Links in citations for GitHub always point to github.com. If your server talks to a GitHub Enterprise Server, search and sync work, but those links won't open the right page. GitLab links use https and the connection's host.
  • A GitLab source is read with the connection's credential, so a connection that needs reconnecting (reauth_required) pauses syncing.
  • A push that arrives while a sync is running is picked up by the next periodic sync.

Read more ​