Repository Management

Connect, organize, and optimize documentation across all your repositories

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

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”:

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

New developer experience:

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

After ULPI

One search across all 23 repositories:

Search: "How do I deploy to production?"

Results (40ms):
1. infrastructure/runbooks/deploy-production.md
2. backend-api/docs/deployment.md
3. frontend-web/README.md#deployment

First result is exactly what you need.

New developer experience:

• Searches: “local development setup”
• Gets setup guides from all relevant repos
• Up and running in 30 minutes
• No Slack questions needed

Time saved: 19 minutes per search × 10 searches/day × 50 developers = 158 hours/day

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:

1. Navigate to Repositories

   Dashboard → Repositories → Click Connect Repository

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

2. 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.

3. Select Repositories

   Choose connection strategy:

   Individual Repos (Recommended)

   Best for first-time setup:

   1. Check boxes next to 2-3 important repos
   2. Click Connect Selected
   3. 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.

   All Repositories

   Best for org-wide deployment:

   1. Toggle Select All Repositories
   2. Click Connect All
   3. All current + future repos automatically connected

   Use case: You’re sold on ULPI, want comprehensive search immediately

   Large orgs (100+ repos): Initial indexing takes 15-30 minutes. Consider starting with critical repos first.

   By Organization

   Best for multi-org setups:

   1. Use Organization filter dropdown
   2. Select specific GitHub org
   3. Choose repos from that org only

   Example: You’re part of:

   • acme-corp (work)
   • open-source-project (personal)
   • consulting-client (contract)

   Only connect acme-corp repositories.

4. 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.

5. Verify Indexing Complete

   Status changes from “Indexing…” to ”✅ Indexed”

   Verify search works:

   1. Ask your AI assistant: “How do I set up local development?”
   2. Should return results from your repository
   3. 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 token

Webhooks: Automatic registration

Bitbucket

Full support:

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

Setup: OAuth connection

Webhooks: Automatic registration

Gitea / Gogs

Full support:

• Self-hosted Gitea
• Gogs instances
• Organizations

Setup: Access token

Webhooks: Manual configuration required

Setup guide →

Self-Hosted Git Servers

Requirements for self-hosted instances:

1. 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)

2. API access enabled

   • Most modern Git servers have API enabled by default

3. Webhook support

   • For auto-sync on git push
   • Manual re-indexing available if webhooks aren’t possible

Enterprise support: Contact [e-mail] 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

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

Code Comments (Optional)

Can be enabled per repository:

/**
 * Authenticates user with OAuth 2.0
 * ✅ This JSDoc comment can be indexed
 *
 * @param {string} token - OAuth token
 * @returns {User} Authenticated user object
 */
function authenticateUser(token) {
  // Regular comments are NOT indexed
  return validateToken(token);
}

Supported comment types:

• JSDoc (JavaScript/TypeScript)
• PHPDoc (PHP)
• Javadoc (Java)
• Docstrings (Python)
• XML comments (C#)

When to enable:

• ✅ You have well-documented code
• ✅ Code comments contain architecture decisions
• ✅ API endpoints documented in code
• ❌ Don’t enable if comments are messy or incomplete

To enable: Repository settings → Index code comments

Wiki Pages (Optional)

GitHub/GitLab wikis can be indexed:

✅ Home.md
✅ Setup-Guide.md
✅ Troubleshooting.md
✅ All wiki pages

When to enable:

• ✅ You actively maintain wiki
• ✅ Wiki has important documentation
• ✅ Wiki is up-to-date
• ❌ Don’t enable if wiki is outdated or abandoned

To enable: Repository settings → Index wiki pages

Pro tip: Consider migrating wiki to /docs directory for better version control.

Automatically Excluded

Files that are never indexed:

Build Artifacts

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

Why excluded: Generated files, not actual documentation

Binary Files

❌ *.pdf
❌ *.docx
❌ *.pptx
❌ *.png, *.jpg, *.svg
❌ *.zip, *.tar.gz

Why excluded: Can’t extract meaningful text for semantic search

Workaround: Convert to Markdown for indexing

Git Internals

❌ .git/
❌ .gitignore
❌ .gitattributes

Why excluded: Not documentation

Large Files

❌ Files >10MB

Why excluded: Too large to process efficiently

Workaround: Split into smaller files

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:

1. Commit .ulpiignore to repository
2. Push to main branch
3. 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 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

What Triggers Re-Index

Full re-index (slow):

• New documentation directory created
• Branch created/deleted
• .ulpiignore file modified
• Manual trigger from dashboard

Partial re-index (fast):

• Existing Markdown file modified
• Documentation file renamed
• Documentation file deleted

No re-index:

• Code files changed (.js, .php, .py)
• Build artifacts updated
• Files in .ulpiignore changed
• Non-documentation changes

Smart indexing: ULPI only re-processes changed files, not entire repository.

Setup (Usually Automatic)

ULPI registers webhooks automatically when you connect a repository.

Verify webhook is active:

1. Dashboard → Repositories → Select repo
2. Look for “Webhook: Active ✅”

If webhook shows “Inactive ❌”:

• You may need admin access to register webhooks
• Firewall may be blocking ULPI
• Manual setup required (see next tab)

Manual Setup (If Needed)

If automatic webhook setup fails:

1. Get Webhook URL

   Dashboard → Repository details → Webhook Settings

   Copy webhook URL:

   https://api.ulpi.io/api/webhooks/vcs/github/{your-repo-id}
   
2. Add to GitHub/GitLab

   GitHub:

   1. Repository → Settings → Webhooks → Add webhook
   2. Payload URL: (paste webhook URL)
   3. Content type: application/json
   4. Events: Select “Just the push event”
   5. Active: ✅ Checked
   6. Add webhook

   GitLab:

   1. Project → Settings → Webhooks
   2. URL: (paste webhook URL)
   3. Trigger: Push events, Tag push events
   4. Enable SSL verification: ✅
   5. Add webhook
3. Verify in ULPI

   Push a test change to docs:

   echo "test" >> README.md
   git commit -am "test webhook"
   git push
   

   Dashboard → Repository → Last webhook: should update within 10 seconds

Troubleshooting: Webhooks Not Firing

Symptoms: Push changes, but search results don’t update

Check webhook status:

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

Common issues:

1. Insufficient permissions

   • Need admin or write access to register webhooks
   • Ask repo admin to grant access
   • Or: Ask admin to manually add webhook

2. Firewall blocking ULPI

   • Corporate firewall blocks api.ulpi.io
   • Whitelist: *.ulpi.io in firewall rules
   • Contact IT for approval

3. Webhook deleted manually

   • Someone deleted webhook from GitHub/GitLab settings
   • Reconnect repository to re-register webhook

4. 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)

Status: Indexed

Meaning: All documentation is indexed and searchable

What you can do:

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

Action: None needed—everything working

🔄 Indexing (In Progress)

Status: Indexing…

Meaning: Currently processing files

When this happens:

• First-time connection
• Manual re-index triggered
• Large webhook update (100+ files changed)

Duration:

Files	Time
Less than 100	30-60s
100-1,000	2-5min
1,000-10,000	5-15min

Action: Wait for completion (check back in 2-5 minutes)

Progress: Dashboard shows “47% complete (234/500 files)”

❌ Failed (Error)

Status: Failed

Meaning: Error occurred during indexing

Common causes:

• Access revoked: Re-authenticate with GitHub/GitLab
• Repository deleted: Disconnect and reconnect
• API rate limit: Wait 1 hour, then retry
• Invalid Markdown: Check for malformed files
• Network error: Temporary issue, retry

Action:

1. Click View Error Details
2. Read error message
3. Fix issue (see troubleshooting below)
4. Click Retry Indexing

Error log: Repository details → Error Log → See full stack trace

⏸️ Paused (Disabled)

Status: Paused

Meaning: Indexing temporarily disabled

When to use:

• Large documentation refactor in progress
• Migrating repository
• Temporarily reduce API usage
• Testing changes before indexing

What happens:

• Existing search results still available
• New changes NOT indexed
• Webhooks NOT processed

Action: Resume indexing when ready:

• Repository details → Resume Indexing

⚠️ Webhook Inactive

Status: Indexed (Webhook Inactive)

Meaning: Docs are indexed, but auto-sync is disabled

Impact:

• Search works for current docs
• New changes WON’T auto-update
• Must manually re-index after pushes

Causes:

• Insufficient permissions to register webhook
• Webhook was manually deleted
• Corporate firewall blocking webhooks

Action: Fix webhook (see manual setup above) or use manual re-indexing

Repository Statistics

View detailed metrics:

Files & Content

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

Activity & Usage

Indexing activity:

Last indexed:            2 hours ago
Last webhook:            15 minutes ago
Total re-indexes:        47 (since connection)

Searches (last 30 days):
├── Total searches:      1,247
├── Searches/day:        41 avg
└── Top queries:
    1. "deployment guide"      (89 searches)
    2. "API authentication"    (67 searches)
    3. "local setup"           (54 searches)

Use this to:

• See which docs are most searched
• Identify documentation gaps
• Verify webhooks are working

Performance Metrics

Search performance:

Indexing time:           1m 23s
Search latency:          42ms avg
Cache hit rate:          78%

Webhook processing:
├── Avg processing time: 45s
├── Fastest:             12s
└── Slowest:             3m 14s (large refactor)

Token efficiency:
├── Avg tokens/search:   2,340
├── vs full docs:        58,000
└── Efficiency:          25x fewer tokens

Use this to:

• Monitor search speed
• Optimize indexing settings
• Report ROI to management

Health & Errors

Error tracking:

Status:                  Healthy ✅

Recent issues:           None

Historical errors (last 30 days):
├── Total errors:        2
├── Rate limit errors:   1 (Nov 8)
└── Network errors:      1 (Nov 3)

Success rate:            99.7%
Uptime:                  100%

Use this to:

• Spot patterns in failures
• Proactively address issues
• Provide data for support tickets

---

Advanced Repository Management

For teams managing many repositories:

Multi-Branch Indexing

Index multiple branches simultaneously:

Use Cases for Multi-Branch Indexing

When to enable:

1. Review docs before merging:

   • Index develop branch
   • Search docs in PR before merge
   • Verify documentation is complete

2. Compare documentation across versions:

   • Index v1.x and v2.x branches
   • Search old docs: "API guide" branch:v1.x
   • Help users on older versions

3. Pre-release documentation:

   • Index feature branches
   • Internal teams see upcoming features
   • External docs stay on main only

Available on: Pro and Enterprise plans

1. Enable Multi-Branch

   Repository settings → Branches → Enable multi-branch indexing

2. 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
   
3. 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:

1. High traffic - Most developers interact with
2. Well-documented - Has quality docs to index
3. 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:

1. Automatic org-wide:

   • Settings → Connect all organization repositories
   • Includes future repos automatically

2. 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

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

By Environment

Production Services:

- production-apis
- production-infrastructure
- production-runbooks

Development/Staging:

- dev-environments
- staging-configs
- testing-docs

Use: Separate prod docs from dev/staging

By Product

Product A:

- product-a-frontend
- product-a-backend
- product-a-mobile

Product B:

- product-b-api
- product-b-admin

Use: Multi-product companies keep docs separated

Create collection:

1. Dashboard → Collections → Create Collection
2. Name: “Frontend Repos”
3. Add repositories to collection
4. 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 stale

Diagnosis checklist:

1. Check Webhook Status

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

   If inactive:

   • Re-register webhook (see manual setup above)
   • Check permissions (need admin access)
2. 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

3. 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

4. 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

5. Manual Re-Index

   Force re-index as last resort:

   Repository details → Re-Index button

   This 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 retry

5. 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:

1. Is it a Markdown file?

   • ✅ .md, .mdx
   • ❌ .txt (unless in /docs)
   • ❌ .pdf, .docx

2. Is it in indexed directory?

   • ✅ /docs/, README.md, /documentation/
   • ❌ /temp/, /private/ (unless explicitly included)

3. Not in .ulpiignore?

   # Check exclusions
   cat .ulpiignore
   

4. File not empty?

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

5. 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:

1. Dashboard → Settings → Git Connections
2. Click Reconnect GitHub
3. Authorize access to private repositories
4. Select repository again

For organization repos:

1. Check org approval:

   • GitHub → Settings → Applications → ULPI
   • If “Pending approval” → Ask org admin to approve

2. Request org admin approval:

   • Send to admin: github.com/orgs/YOUR_ORG/settings/oauth_application_policy
   • Admin: Find “ULPI Documentation”
   • Admin: Click “Grant access”

3. 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: [e-mail]

⚠️ 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:

1. Review quarterly:

   • Set calendar reminder
   • Read through all docs
   • Update outdated info

2. Version indicators:

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

3. Archive old docs:

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

   Add to .ulpiignore:

   /docs/archive/
   

4. 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 repositories

Master semantic search techniques

API Integration

Access documentation programmatically via REST API

Build custom search workflows

How It Works

Understand the indexing and search technology

Deep dive into architecture

Getting Started

Connect more repositories and configure AI tools

Expand your searchable knowledge base

---

Need help with repositories?

• 📧 Email: [e-mail]
• 📚 Docs: docs.ulpi.io
• 💬 Slack: ulpi.io/slack

Average response time: Under 2 hours during business hours

Enterprise support: Dedicated Slack channel + priority response