Connecting Your First Repository

Connecting a repository to Codebase Context Fabric is the first step toward org-wide AI cost savings. Once connected, the system builds shared context artifacts that eliminate redundant LLM calls across your entire engineering team.

Use this page when

• You are connecting your first repository to Codebase Context Fabric.
• You need the step-by-step process for repo connection, credential setup, and artifact monitoring.
• You want to troubleshoot issues with artifact builds or webhook registration.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

What Happens When You Connect a Repo

When you connect a repository, Keeptrusts:

1. Clones the repository to a secure internal store
2. Enqueues artifact warmers for all enabled artifact types
3. Begins building fabric artifacts (repo_map, dependency_graph, test_map, api_inventory, symbol_index, embedding_index, file_summary)
4. Registers a webhook (or poll schedule) for commit-triggered refreshes
5. Makes artifacts available to the org-shared cache as each one completes

The initial build is the most expensive part of the entire caching lifecycle. After this, incremental updates triggered by new commits cost very little.

Prerequisites

Before connecting a repository:

• You have admin access to the Keeptrusts console
• You have a git personal access token (PAT) or deploy key with read access to the repo
• The repository is accessible from your Keeptrusts deployment (network/firewall rules permit)
• The worker_cache_warmer binary is running and healthy
• Your org wallet has sufficient balance for the initial fill

Required Permissions

The git credential needs read-only access to:

• Repository contents (code, files)
• Branch list and commit history
• Webhook registration (optional, for push-triggered refresh)

Keeptrusts never writes to your repository. No push access is needed.

Step-by-Step Connection

1. Navigate to Repository Settings

Open the Keeptrusts console and go to Settings → Repositories → Connect Repository.

2. Enter Repository Details

Field	Example	Notes
Git URL	https://github.com/your-org/your-repo.git	HTTPS or SSH format
Authentication	Personal access token	Or SSH key, deploy token
Credential	ghp_xxxxxxxxxxxx	Stored encrypted (AES-GCM-SIV)
Branches	main, develop	Select branches to track
Auto-build fabric	✓ Enabled	Triggers immediate artifact creation

3. Test Connection

Click Test Connection to verify:

• Network connectivity to the git host
• Credential validity
• Branch accessibility
• Webhook endpoint reachability (if configured)

4. Connect

Click Connect Repository. The system begins cloning immediately.

5. Monitor Progress

Navigate to Repositories → [Repo Name] → Fabric Status to watch artifact creation:

repo_map .............. Building → Ready (45s)
dependency_graph ...... Building → Ready (2m)
test_map .............. Building → Ready (1m 30s)
api_inventory ......... Building → Ready (3m)
symbol_index .......... Building → Ready (4m)
file_summary .......... Building → Ready (12m)
embedding_index ....... Building → Ready (25m)

Initial Fill: The Investment Phase

The initial artifact build is your primary investment in shared caching. Understanding its cost helps you budget appropriately.

Why Initial Fill Is Expensive

Building fabric artifacts requires LLM calls:

• file_summary: One LLM call per source file to generate a natural language summary
• embedding_index: One embedding call per code chunk (typically 100-500 token chunks)
• api_inventory: LLM calls to analyze route handlers and extract schemas
• repo_map: A few LLM calls to synthesize the overall structure

For a repository with 1,000 source files:

Artifact	Estimated LLM calls	Estimated cost
file_summary	~1,000	$3-8
embedding_index	~5,000 chunks	$2-5
api_inventory	~50-200	$0.50-2
repo_map	3-5	$0.02-0.05
symbol_index	0 (static analysis)	$0
dependency_graph	0 (static analysis)	$0
test_map	5-20	$0.05-0.20
Total initial fill		$6-16

This one-time investment unlocks ongoing savings of $150-200/day for a 100-engineer team.

Why Subsequent Updates Are Cheap

After the initial fill, only changed files trigger re-processing:

• A typical day has 20-50 file changes across a team
• Only changed files need new summaries and embeddings
• Structural artifacts (repo_map, dependency_graph) only rebuild when structure changes
• Daily incremental cost: $0.10-0.50 (vs. $6-16 initial fill)

Commit-Triggered Refresh

When new commits land on tracked branches, Keeptrusts refreshes affected artifacts:

What Triggers a Refresh

Change type	Artifacts refreshed
Source file modified	file_summary, embedding_index, symbol_index
New file added	All artifacts for the new file + repo_map if structural
File deleted	repo_map, dependency_graph, relevant indexes
Package manifest changed	dependency_graph
Test file changed	test_map, file_summary for the test
Route/handler changed	api_inventory

Refresh Timing

• Webhook mode: Refresh begins within 30 seconds of push
• Poll mode: Refresh begins at next poll interval (configurable, default 5 minutes)

Refresh Cost

Incremental refreshes are inexpensive because they only process changed files:

Refresh cost = (changed_files × avg_summary_cost) + (changed_chunks × embedding_cost)

For a typical commit touching 3-5 files: $0.01-0.05.

Multiple Branches

You can track multiple branches per repository. Each branch maintains its own set of fabric artifacts:

• Main/default branch: Primary fabric source, highest cache value
• Development branches: Useful for teams that spend most time on a develop branch
• Feature branches: Generally not worth tracking (short-lived, low reuse)

Branch Strategy Recommendation

Start with your main branch only. Add additional branches only if:

• A significant portion of your team works primarily on that branch
• The branch diverges substantially from main (making main's artifacts less relevant)
• The branch is long-lived (weeks or months, not days)

Troubleshooting Common Connection Issues

"Connection refused" or timeout

Cause: Network path between Keeptrusts and git host is blocked.

Fix:

• Verify firewall rules allow outbound HTTPS (port 443) to your git host
• For self-hosted git (GitLab, Gitea), ensure the internal DNS resolves from the Keeptrusts deployment
• Check that any proxy configuration is set in the Keeptrusts environment

"Authentication failed"

Cause: Invalid or expired credentials.

Fix:

• Verify the token has not expired
• Confirm the token has read access to the specific repository
• For GitHub fine-grained tokens, check the repository is in the token's scope
• For SSH keys, verify the key is registered with the git host

"Webhook registration failed"

Cause: The git host cannot reach the Keeptrusts webhook endpoint.

Fix:

• Ensure your Keeptrusts deployment has a publicly reachable URL (or one reachable from your git host)
• Verify the webhook secret is configured correctly
• Fall back to poll mode if webhook is not feasible

Artifacts stuck in "Queued"

Cause: The worker_cache_warmer binary is not running or is overloaded.

Fix:

• Check that the warmer worker is deployed and healthy: docker compose logs worker-cache-warmer
• If the queue is large (many repos connected simultaneously), wait for capacity
• Check worker logs for errors (credential issues, OOM, rate limiting from LLM providers)

Artifacts in "Error" state

Cause: LLM provider returned an error during artifact build.

Fix:

• Check the error details in the artifact status panel
• Common causes: rate limiting (wait and retry), context too long (large files), provider outage
• Click Retry to re-enqueue the failed artifact

After Connection

Once all artifacts reach Ready status:

1. Verify cache attachment: Send a test prompt and check that fabric_context_attached: true appears in the event metadata
2. Monitor hit rate: Watch the cache hit rate climb over the next hours as engineers' prompts start matching cached responses
3. Add more repos: Repeat this process for other repositories your team shares

Next steps

• Setting Up Codebase Context Fabric — configure artifact types and refresh behavior
• Cache Tiers Explained — understand how fabric artifacts flow into cache
• Your First 24 Hours — watch the economics play out in real time

For AI systems

• Canonical terms: Keeptrusts, repository connection, git-linked repo, fabric artifacts, initial fill, worker_cache_warmer, artifact warmers.
• Exact feature/config names: Settings → Repositories → Connect Repository, Auto-build fabric, artifact types (repo_map, dependency_graph, file_summary, test_map, api_inventory, symbol_index, embedding_index), worker_cache_warmer binary.
• Best next pages: Setting Up Codebase Context Fabric, Cache Tiers Explained, Your First 24 Hours.

For engineers

• You need admin console access plus a read-only git PAT or deploy key — Keeptrusts never writes to your repository.
• Test Connection verifies network connectivity, credential validity, branch access, and webhook reachability before committing.
• Monitor artifact creation at Repositories → [Repo] → Fabric Status — all artifacts build in parallel.
• If artifacts are stuck in "Queued", confirm worker_cache_warmer is running: docker compose logs worker-cache-warmer.
• After all artifacts reach Ready, verify cache attachment by checking fabric_context_attached: true in event metadata.

For leaders

• Initial artifact build is the primary cost investment — for a 1,000-file repo, expect $10-25 in LLM calls for full indexing.
• The webhook-triggered refresh model means ongoing maintenance cost is minimal (only changed files re-index on commit).
• Credentials are stored encrypted (AES-GCM-SIV) — no plaintext tokens in the database.
• Prioritize connecting high-traffic shared repos first for maximum immediate ROI; each additional repo independently builds and delivers value.