Repositories
Connect your Git repositories so Praxis agents can learn how your code is built and how your repositories relate, and draw on that when they work.
Your repository knowledge base is what Praxis knows about your code. You connect a repository, an indexing agent reads it on demand, and agents draw on what it learned whenever they work on a task that touches that code. Connecting a repository only registers it; reading it and building its entry is a separate, manual step.
Connect a repository
Adding a repository needs a Git credential, which you set up once under Settings > Integrations. Praxis supports GitHub, GitLab, and Bitbucket, and you can connect a credential in three ways: a personal access token (GitHub or GitLab) or an API token (Bitbucket); a GitHub App installation, which gives organization-wide access to GitHub repositories without individual tokens; or an import of a Git account already configured in your Facets control plane, where Praxis fetches its access token and stores it encrypted. Every token is encrypted before storage, belongs to the person who added it, and is scoped to your organization.
With a credential in place, connect a repository from the Repositories page:
- Select Add repository.
- Choose the credential to authenticate with, a token or your GitHub App installation.
- Select Browse Repositories to list everything that credential can reach, then pick the one to add. To add a repository the list does not surface, paste its URL instead.
- Confirm to add it.
Browsing marks repositories you have already added so you don't add them twice, and flags private ones. After a repository is connected, you can change its display name and description; its source URL and credential stay fixed.
Populate the knowledge base
Connecting a repository does not read it. To build or refresh an entry, select Populate on that row, which runs the indexing agent over the repository. This is deliberate: you decide when each repository gets read, and nothing is indexed automatically when you add it. While a run is in progress the row shows it populating and refreshes on its own when the run finishes.
Each repository carries a status:
| Status | What it means |
|---|---|
| Not indexed | Connected, but never read. |
| Parse-only | A basic entry exists, such as languages and build commands, without written observations. |
| Enriched | The agent has added written observations on top of those facts. |
Once indexed, a repository shows the short commit it was read at and how long ago. Run Populate again after new commits, and the agent indexes only what changed since the last indexed commit rather than re-reading the whole repository. From a repository's entry, you can open the transcript of the run that produced it to see exactly what the agent did.
What the knowledge base holds
Open a repository with View to read its entry. Reading a repository produces a few kinds of knowledge:
- Facts about how the repository is built: the languages it uses, its build and test commands, and its entry points.
- Observations, a running log of what the agent notices in the code, added to over time and deduplicated rather than overwritten.
- Connections to other repositories, each typed so Praxis knows the nature of the link: one repository can depend on another, call its API, produce a resource, or consume one. Connections show both ways, the repositories this one reaches and the ones that reach it.
- Signals: the external APIs, message topics, and libraries the code references.
You can also add your own dated notes to an entry, so anything your team knows that the code doesn't spell out sits alongside what the agent found. A repository has to be indexed at least once before you can add a note.
How the indexing agent is scoped
Indexing reads your code; it doesn't change it. The agent works on a shallow, throwaway clone in an isolated working directory, reads and searches the files, and records what it learns to the knowledge base, a separate store. Building an entry doesn't commit to or push to your repository.
Every repository and every entry is scoped to your organization. The indexing agent only sees repositories in your organization, and that scoping is set on the server where the agent can't change it, so one organization's code never surfaces in another's session.
The credential you connect isn't only for indexing. Praxis stores it at the organization level and agents across the product use it, so when you ask an agent to open a pull request or push a branch, it works against your repositories with that same credential and its permissions.
Give each repository token the least access its tasks need. Read-only is enough to index code and build the knowledge base; grant write access only if you expect agents to open pull requests or push branches.
For where Praxis runs, how it isolates each run, and how it encrypts and injects credentials, see How Praxis works.
Related
- Catalog - The map of your running services and resources
- How Praxis works - The execution and security model behind your agents
Integrations & Credentials
Connect Praxis to your cloud, Git, Kubernetes, chat, and observability systems, then manage the encrypted secrets your tools and MCP servers use to reach anything else.
Web Component Builder
Build custom Facets dashboard components by describing them to Praxis, which scaffolds the code, deploys it to GitHub Pages, and embeds the result in your dashboard.