Manage Documentation Across All Your Repositories

Your team has documentation scattered across 23 repositories. Frontend docs in one place. Backend in another. Infrastructure somewhere else. Finding anything requires knowing which repo to search—and most new developers have no idea. ULPI fixes this by connecting all your repositories into one searchable knowledge base. This guide shows you:

🔗 How to connect repositories (2 minutes per repo)
⚙️ Configure what gets indexed (exclude drafts, temp files, etc.)
🔄 Keep documentation automatically synced via webhooks
📊 Monitor indexing status and troubleshoot issues
🚀 Optimize for large organizations with 100+ repos

First time? Start with Getting Started for initial setup.Want to search? See Search Features for query techniques.

The Problem: Documentation Chaos

Your organization’s reality:

Before ULPI
After ULPI

23 repositories, each with their own docs:

backend-api/         → API docs in /docs
frontend-web/        → Component docs in /src/components
mobile-app/          → Setup in README only
infrastructure/      → Runbooks in /runbooks
auth-service/        → Auth docs in wiki
payment-service/     → No docs (comments only)
notifications/       → Docs in Notion (not in repo)
legacy-monolith/     → 5-year-old docs, probably outdated
... 15 more repos

To find “how to deploy”:

Guess which repo has deployment docs
Clone repo (if you don’t have it)
Search through /docs, README.md, /runbooks
Find outdated doc from 2020
Ask in Slack: “Where are the current deployment docs?”
20 minutes wasted

New developer experience:

Doesn’t know repos exist
No idea where to look
Asks same questions for weeks

ULPI makes all your documentation searchable—no matter which repo it’s in.

Quick Start: Connect Your First Repository

Get searchable docs in under 2 minutes:

Navigate to Repositories

Dashboard → Repositories → Click Connect Repository

Pro tip: Start with your most important repository (usually backend-api or main app)

Authorize Access

Click “Connect GitHub” (or GitLab/Bitbucket)ULPI requests read-only access:

✅ Read repository contents
✅ Register webhooks (for auto-sync)
❌ No write access (cannot modify code)

Security: OAuth with encrypted token storage. Revocable anytime from GitHub settings.

Select Repositories

Choose connection strategy:

Individual Repos (Recommended)
All Repositories
By Organization

Best for first-time setup:

Check boxes next to 2-3 important repos
Click Connect Selected
See ULPI in action before connecting everything

Recommended:

Main application repo
Backend API repo
Infrastructure/deployment repo

Why start small? Verify ULPI works well before organization-wide rollout.

Wait for Indexing

ULPI automatically indexes your documentation:What’s happening:

Discovering all documentation files
Parsing Markdown content
Generating semantic embeddings
Building search index

Time estimates:

Repository Size	Files	Indexing Time
Small (starter)	Less than 100	30-60 seconds
Medium (typical app)	100-1,000	2-5 minutes
Large (monorepo)	1,000-10,000	5-15 minutes

You can configure MCP while waiting! Jump to Getting Started Step 3.

Verify Indexing Complete

Status changes from “Indexing…” to ”✅ Indexed”Verify search works:

Ask your AI assistant: “How do I set up local development?”
Should return results from your repository
Click the GitHub link to verify it’s YOUR docs

Success! Your documentation is now searchable by AI.

Total time: 2 minutes + automatic indexing

Supported Git Platforms

ULPI works with all major Git providers:

GitHub

Full support:

GitHub.com (public and private)
GitHub Enterprise Server (self-hosted)
Organizations and personal accounts
All repository types

Setup: OAuth connection (1 click)Webhooks: Automatic registration

GitLab

Full support:

GitLab.com
Self-hosted GitLab (CE and EE)
Groups and subgroups
Project access tokens

Setup: OAuth or access tokenWebhooks: Automatic registration

Bitbucket

Full support:

Bitbucket Cloud
Bitbucket Server (self-hosted)
Workspaces and projects
Repository access keys

Setup: OAuth connectionWebhooks: Automatic registration

Gitea / Gogs

Full support:

Self-hosted Gitea
Gogs instances
Organizations

Setup: Access tokenWebhooks: Manual configuration requiredSetup guide →

Self-Hosted Git Servers

Requirements for self-hosted instances:

Publicly accessible URL (ULPI needs to reach your server)
- OR: VPN connection to ULPI (Enterprise plan)
- OR: Webhook proxy (we can help set this up)
API access enabled
- Most modern Git servers have API enabled by default
Webhook support
- For auto-sync on git push
- Manual re-indexing available if webhooks aren’t possible

Enterprise support: Contact sales@ulpi.io for VPN peering or on-premise deployment.

What Gets Indexed (and What Doesn’t)

ULPI is smart about what to index:

Automatically Included

Documentation Files
Code Comments (Optional)
Wiki Pages (Optional)

Primary documentation:

✅ README.md (root and all subdirectories)
✅ docs/ directory (all Markdown files)
✅ documentation/ directory
✅ .github/ directory (CONTRIBUTING.md, ISSUE_TEMPLATE, etc.)
✅ All .md and .mdx files anywhere
✅ CONTRIBUTING.md, CODE_OF_CONDUCT.md
✅ CHANGELOG.md, SECURITY.md
✅ Architecture Decision Records (ADRs)

Example structure:

myrepo/
├── README.md                    ✅ Indexed
├── docs/
│   ├── getting-started.md       ✅ Indexed
│   ├── api/
│   │   └── authentication.md    ✅ Indexed
│   └── guides/
│       └── deployment.md        ✅ Indexed
├── .github/
│   ├── CONTRIBUTING.md          ✅ Indexed
│   └── pull_request_template.md ✅ Indexed

Automatically Excluded

Files that are never indexed:

Build Artifacts
Binary Files
Git Internals
Large Files

❌ node_modules/
❌ vendor/
❌ dist/
❌ build/
❌ .next/
❌ out/
❌ target/
❌ .cache/

Why excluded: Generated files, not actual documentation

Custom Exclusions with .ulpiignore

Exclude specific files or patterns: Create .ulpiignore in repository root:

# .ulpiignore (syntax like .gitignore)

# Exclude generated API docs
/docs/api/generated/
/docs/auto-generated/

# Exclude drafts and WIP docs
**/drafts/**
**/*.draft.md
**/*.wip.md

# Exclude old/deprecated docs
/docs/archive/
/docs/deprecated/

# Exclude specific files
CHANGELOG.md          # Too noisy for search
TODO.md               # Internal only
NOTES.md              # Scratchpad

# Exclude translations (if you only want English)
/docs/i18n/
/docs/locales/

# Include specific files (negate exclusion)
!docs/archive/important-historical-doc.md

Pattern syntax:

* - Match any characters in filename
** - Match any directories
! - Negate pattern (include files that would be excluded)
/ - Match from repo root

To apply changes:

Commit .ulpiignore to repository
Push to main branch
Dashboard → Repository → Re-Index

Verify exclusions: Repository details → Indexed Files → Search for filename

Automatic Sync via Webhooks

Your documentation stays up-to-date automatically:

How Webhooks Work

Automatic Flow
What Triggers Re-Index
Setup (Usually Automatic)
Manual Setup (If Needed)

What happens when you push:Timeline:

Less than 1 second: Webhook received
5-10 seconds: Job queued and fetched
20-40 seconds: Re-indexed
30-60 seconds: Searchable by AI

Total: 30-60 seconds from push to searchable

Troubleshooting: Webhooks Not Firing

Symptoms: Push changes, but search results don’t updateCheck webhook status:

Dashboard → Repositories → Select repo
Look for “Webhook: Active ✅” or “Webhook: Inactive ❌”

Common issues:

Insufficient permissions
- Need admin or write access to register webhooks
- Ask repo admin to grant access
- Or: Ask admin to manually add webhook
Firewall blocking ULPI
- Corporate firewall blocks api.ulpi.io
- Whitelist: *.ulpi.io in firewall rules
- Contact IT for approval
Webhook deleted manually
- Someone deleted webhook from GitHub/GitLab settings
- Reconnect repository to re-register webhook
Rate limiting (GitHub)
- Hit GitHub API rate limit (5,000 requests/hour)
- Wait 1 hour and try again
- Or: Manually trigger re-index

Manual workaround: Repository details → Re-Index button (forces re-index without webhook)

Repository Status & Monitoring

Track indexing status for all repositories:

Status Indicators

✅ Indexed (Ready)
🔄 Indexing (In Progress)
❌ Failed (Error)
⏸️ Paused (Disabled)
⚠️ Webhook Inactive

Status: IndexedMeaning: All documentation is indexed and searchableWhat you can do:

Search works normally
AI assistants have access
Webhooks auto-sync on push

Action: None needed—everything working

Repository Statistics

View detailed metrics:

Files & Content
Activity & Usage
Performance Metrics
Health & Errors

What’s indexed:

Total files indexed:     247
├── Markdown files:      198
├── README files:        32
├── Code comments:       0 (disabled)
└── Wiki pages:          17

Total size:              4.2 MB
Average file size:       17 KB
Largest file:            156 KB (docs/api-reference.md)

Total chunks:            1,234
Average chunks/file:     5.2

Use this to:

Verify all expected docs are indexed
Identify large files that might need splitting
See if code comments should be enabled

Advanced Repository Management

For teams managing many repositories:

Multi-Branch Indexing

Index multiple branches simultaneously:

Use Cases for Multi-Branch Indexing

When to enable:

Review docs before merging:
- Index develop branch
- Search docs in PR before merge
- Verify documentation is complete
Compare documentation across versions:
- Index v1.x and v2.x branches
- Search old docs: "API guide" branch:v1.x
- Help users on older versions
Pre-release documentation:
- Index feature branches
- Internal teams see upcoming features
- External docs stay on main only

Available on: Pro and Enterprise plans

Enable Multi-Branch

Repository settings → Branches → Enable multi-branch indexing

Add Branches

Click Add Branch and configure:Specific branch:

develop
staging
production

Branch patterns:

feature/*        # All feature branches
release/*        # All release branches
hotfix/*         # All hotfix branches

Version branches:

v1.x
v2.x
v3.x

Search Specific Branches

Query syntax:

"API changes" branch:develop
"deployment" branch:v2.x
"new features" branch:feature/oauth-upgrade

Compare branches:

Search in main:    "authentication guide" branch:main
Search in develop: "authentication guide" branch:develop

See differences between production and development docs.

Cost consideration: Each branch counts as separate repository for indexing quota.

1 repo + 2 branches = 3 repos for billing
Consider which branches are truly needed

Organization-Wide Deployment

Best practices for rolling out ULPI across large organizations:

Phase 1: Pilot (Weeks 1-2)

Start with 3-5 critical repositories:Recommended pilot repos:

✅ Main application (most searched)
✅ Backend API (well-documented)
✅ Infrastructure/runbooks (high value)

Goals:

Verify ULPI works with your setup
Gather feedback from early adopters
Identify documentation gaps
Measure search usage metrics

Success criteria:

80%+ of searches return relevant results
AI assistants successfully use docs
5+ active users searching daily

Phase 2: Expand (Weeks 3-4)

Connect 10-20 additional repositories:Prioritize by:

High traffic - Most developers interact with
Well-documented - Has quality docs to index
Critical services - Auth, payments, core APIs

Communication:

Announce in eng-all Slack
Share pilot success metrics
Provide ULPI setup guide
Offer office hours for questions

Monitor:

Search volume per repository
Which docs get searched most
Error rates and indexing issues

Phase 3: Organization-Wide (Week 5+)

Connect all remaining repositories:Bulk connection options:

Automatic org-wide:
- Settings → Connect all organization repositories
- Includes future repos automatically
Selective by team:
- Frontend team: Connect frontend repos
- Backend team: Connect backend repos
- etc.

Governance:

Designate ULPI admins per team
Create .ulpiignore guidelines
Document best practices
Regular audits of indexed repos

Training:

Record demo video
Write internal search tips guide
Add to onboarding checklist

Ongoing Maintenance

Monthly tasks:

Review repositories with failed indexing
Archive disconnected old repos
Update documentation standards
Review most-searched queries (find doc gaps)

Quarterly:

Audit .ulpiignore files across repos
Review search analytics
Survey developer satisfaction
Optimize slow-indexing repos

Annually:

Review organization-wide metrics
Calculate ROI (time saved)
Plan documentation improvements

Repository Collections

Group related repositories for easier management:

By Team
By Environment
By Product

Frontend Collection:

- web-app
- mobile-app
- component-library
- design-system

Backend Collection:

- api-gateway
- auth-service
- payment-service
- notification-service

Use: Search only frontend docs when working on UI

Create collection:

Dashboard → Collections → Create Collection
Name: “Frontend Repos”
Add repositories to collection
Share collection with team

Search within collection:

"authentication" collection:frontend

Troubleshooting Common Issues

🔍 Documentation Not Updating After Push

Symptom: Pushed changes to docs, but search results are staleDiagnosis checklist:

Check Webhook Status

Dashboard → Repository → Look for “Webhook: Active ✅”If inactive:

Re-register webhook (see manual setup above)
Check permissions (need admin access)

Verify File Location

Is file in indexed directory?

/docs/**/*.md ✅
/documentation/**/*.md ✅
README.md ✅
/src/utils/README.md ✅
/temp/draft.md ❌ (if in .ulpiignore)

Check: Repository → Indexed Files → Search for your file

Check .ulpiignore

# Check if file is excluded
cat .ulpiignore

# Common issue: excluded too broadly
/docs/  # ❌ Excludes ALL docs
/docs/drafts/  # ✅ Excludes only drafts

Fix: Update .ulpiignore, commit, re-index

Verify Branch

Pushing to indexed branch?Most repos index main only.

# Check current branch
git branch

# If on different branch:
git checkout main
git merge your-feature-branch
git push origin main

Or: Enable multi-branch indexing for your branch

Manual Re-Index

Force re-index as last resort:Repository details → Re-Index buttonThis triggers:

Full re-scan of repository
Re-processing of all docs
Cache invalidation

Time: 30s - 5min depending on repo size

Still not working? Contact support with:

Repository name
File path that’s not updating
Last push timestamp
Webhook status

⏱️ Slow Indexing (Taking >10 Minutes)

Normal indexing times:

Less than 100 files: 30s - 1min ✅
100-1,000 files: 1-3min ✅
1,000-10,000 files: 3-5min ✅
10,000+ files: 5-15min ⚠️

If taking much longer:1. Check file count:

Dashboard → Repository → "Total files: 47,234"

Monorepo with many docs? Consider:

Using .ulpiignore to exclude unneeded docs
Splitting into multiple repos
Indexing only /docs directory

2. Check for large files:

Dashboard → Repository → "Largest file: 45 MB"

Files >10MB are skipped. If many large files:

Split into smaller files
Convert large PDFs to Markdown
Use .ulpiignore to exclude

3. Check network issues:

ULPI must fetch all files from GitHub/GitLab
Slow network = slow indexing
Enterprise: Use VPC peering for faster access

4. Check GitHub API rate limits:

https://api.github.com/rate_limit

If limited: Wait 1 hour and retry5. Contact support:

If >10,000 files: We can optimize your indexing
If >30min: Something is wrong, we’ll investigate

❌ Indexing Failed (Error)

Click error message for details. Common errors:“Access Denied” / “401 Unauthorized”:

OAuth token expired or revoked
Fix: Reconnect repository (re-authenticate)

“Repository Not Found” / “404”:

Repository deleted or renamed
Fix: Disconnect old repo, connect new one

“Rate Limit Exceeded”:

Hit GitHub API limit (5,000 requests/hour)
Fix: Wait 1 hour, retry automatically

“Invalid Markdown Syntax”:

Malformed Markdown file causing parser error
Fix: Check error log for file name, fix syntax

“Network Error” / “Timeout”:

Temporary network issue
Fix: Retry indexing (usually resolves itself)

“Webhook Payload Too Large”:

Pushed >1,000 files at once
Fix: Manual re-index (handles large changes)

View full error:

Repository details → Error Log
Copy error message for support ticket

📄 Missing Files (Expected File Not Indexed)

File not showing up in search?Checklist:

Is it a Markdown file?
- ✅ .md, .mdx
- ❌ .txt (unless in /docs)
- ❌ .pdf, .docx
Is it in indexed directory?
- ✅ /docs/, README.md, /documentation/
- ❌ /temp/, /private/ (unless explicitly included)
Not in .ulpiignore?
```
# Check exclusions
cat .ulpiignore
```

File not empty?

# Check file size
ls -lh docs/my-file.md
# Should be >0 bytes

UTF-8 encoding?

# Check encoding
file -I docs/my-file.md
# Should show: charset=utf-8

Verify file was indexed:

Repository details → Indexed Files
Search for filename
If not listed → Check above conditions

Force inclusion:

Add to .ulpiignore with negation:

# Include specific file
!temp/important-doc.md

🔐 Can't Access Private Repository

Symptoms: Repository shows “Access Denied”For personal repos:

Dashboard → Settings → Git Connections
Click Reconnect GitHub
Authorize access to private repositories
Select repository again

For organization repos:

Check org approval:
- GitHub → Settings → Applications → ULPI
- If “Pending approval” → Ask org admin to approve
Request org admin approval:
- Send to admin: github.com/orgs/YOUR_ORG/settings/oauth_application_policy
- Admin: Find “ULPI Documentation”
- Admin: Click “Grant access”
Verify you have access:
- You must have Read access to repository
- Check: github.com/YOUR_ORG/REPO/settings/access

Still not working?

Try disconnecting and reconnecting repository
Verify OAuth token has correct scopes
Contact support: support@ulpi.io

⚠️ Webhook Inactive (Auto-Sync Disabled)

Symptom: Status shows “Webhook: Inactive ❌”Impact:

Docs are searchable (current version)
New changes WON’T auto-update
Must manually re-index after each push

Common causes:1. Insufficient permissions:

Need admin or write access
Fix: Ask repo admin to grant access

2. Firewall blocking:

Corporate firewall blocks api.ulpi.io
Fix: Whitelist *.ulpi.io in firewall

3. Webhook manually deleted:

Someone removed webhook from GitHub
Fix: Reconnect repository to re-register

4. GitHub Enterprise behind VPN:

ULPI can’t reach your server
Fix: Enterprise plan with VPN peering

Manual setup:

See “Manual Webhook Setup” tab above
Requires admin access to repository

Workaround:

Use manual re-index after each push
Not ideal, but works if webhooks can’t be enabled

Best Practices for Documentation

Optimize your repositories for better search:

📁 Standard Directory Structure

Recommended structure:

your-repo/
├── README.md              # Quick start
├── docs/
│   ├── getting-started.md # Setup guide
│   ├── api/
│   │   ├── authentication.md
│   │   └── endpoints.md
│   ├── guides/
│   │   ├── deployment.md
│   │   └── troubleshooting.md
│   └── architecture/
│       ├── decisions/     # ADRs
│       └── diagrams/
├── CONTRIBUTING.md
└── .ulpiignore

Why this works:

Easy to find docs (always /docs)
Logical organization by topic
ULPI indexes everything

📝 Clear, Descriptive Filenames

Good filenames:

✅ authentication-guide.md
✅ deployment-to-aws.md
✅ troubleshooting-500-errors.md
✅ api-rate-limiting.md

Bad filenames:

❌ doc1.md
❌ notes.md
❌ stuff.md
❌ temp.md

Impact on search:

Filenames are used in ranking
Descriptive names = better results

🔄 Update Docs with Code

Document in the same PR:

PR #247: Add OAuth 2.0 authentication

Changed files:
✅ src/auth/oauth.js          (code)
✅ docs/authentication.md     (docs)
✅ README.md                  (updated)

Benefits:

Docs never get stale
Reviewers catch doc issues
Webhooks auto-index on merge
AI sees updated docs instantly

📑 Use Headings & Structure

Well-structured docs:

# Authentication Guide

## Overview
Brief intro...

## Quick Start
Step-by-step...

## OAuth 2.0
### Setup
### Token Refresh
### Error Handling

## Troubleshooting
### Common Errors
### Debug Tips

Why:

Semantic search uses headings
Chunking respects sections
Better result snippets

Documentation Quality Tips

✍️ Write for Your Audience

New developers need:

Clear setup instructions
Prerequisites listed
Step-by-step guides
Screenshots/diagrams

Experienced developers need:

API references
Architecture decisions
Performance tuning
Troubleshooting guides

Write both types:

getting-started.md for newbies
architecture/decisions/ for veterans

🔗 Link Between Docs

Cross-reference related docs:

# Deployment Guide

Prerequisites:
- [Local setup complete](./getting-started.md)
- [Environment configured](./configuration.md)
- [Tests passing](./testing.md)

See also:
- [Rollback procedure](./rollback.md)
- [Monitoring](./monitoring.md)

Benefits:

Helps readers find related info
ULPI follows links for context
Better semantic understanding

📅 Keep Docs Current

Strategies:

Review quarterly:
- Set calendar reminder
- Read through all docs
- Update outdated info

Version indicators:

> **Version:** v2.0
> **Last updated:** 2025-01-15
> **Deprecated:** v1.0 docs moved to archive/

Archive old docs:

docs/
├── current/         # Latest docs
└── archive/
    ├── v1.x/
    └── deprecated/

Add to .ulpiignore:

/docs/archive/

Changelog: Track doc changes in docs/CHANGELOG.md

🎯 Write for Search

SEO for docs (helps ULPI too):Include keywords naturally:

❌ "Setup process"
✅ "Local development environment setup on macOS"

Answer questions:

# How to Deploy to Production

## What is the deployment process?
## Where are the deployment scripts?
## When should I deploy?
## Who can deploy to production?

Use synonyms:

# Authentication (Login, User Verification)

This guide covers authentication, also known as
login, sign-in, and user verification...

Result: Better search results for varied queries

Next Steps

Search Your Docs

Learn how to search across all connected repositoriesMaster semantic search techniques

API Integration

Access documentation programmatically via REST APIBuild custom search workflows

How It Works

Understand the indexing and search technologyDeep dive into architecture

Getting Started

Connect more repositories and configure AI toolsExpand your searchable knowledge base

Need help with repositories?

📧 Email: support@ulpi.io
📚 Docs: docs.ulpi.io
💬 Slack: ulpi.io/slack

Average response time: Under 2 hours during business hoursEnterprise support: Dedicated Slack channel + priority response

Getting Started

Documentation

Skills

Coordination

Memory

Hooks

Tasks

Help & Security

​Manage Documentation Across All Your Repositories

​The Problem: Documentation Chaos

​Quick Start: Connect Your First Repository

​Supported Git Platforms

GitHub

GitLab

Bitbucket

Gitea / Gogs

​What Gets Indexed (and What Doesn’t)

​Automatically Included

​Automatically Excluded

​Custom Exclusions with .ulpiignore

​Automatic Sync via Webhooks

​How Webhooks Work

​Repository Status & Monitoring

​Status Indicators

​Repository Statistics

​Advanced Repository Management

​Multi-Branch Indexing

​Organization-Wide Deployment

​Repository Collections

​Troubleshooting Common Issues

​Best Practices for Documentation

📁 Standard Directory Structure

📝 Clear, Descriptive Filenames

🔄 Update Docs with Code

📑 Use Headings & Structure

​Documentation Quality Tips

​Next Steps

Search Your Docs

API Integration

How It Works

Getting Started

Manage Documentation Across All Your Repositories

The Problem: Documentation Chaos

Quick Start: Connect Your First Repository

Supported Git Platforms

What Gets Indexed (and What Doesn’t)

Automatically Included

Automatically Excluded

Custom Exclusions with .ulpiignore

Automatic Sync via Webhooks

How Webhooks Work

Repository Status & Monitoring

Status Indicators

Repository Statistics

Advanced Repository Management

Multi-Branch Indexing

Organization-Wide Deployment

Repository Collections

Troubleshooting Common Issues

Best Practices for Documentation

Documentation Quality Tips

Next Steps