turash/k8s/registry/WOODPECKER_SETUP.md

Woodpecker Repository Setup Guide

Issue: Repository Not Showing in Sync UI

Problem

When syncing repositories in Woodpecker UI, some repositories (especially private ones) may not appear due to:

1. Pagination Limits: GitHub API pagination limits (default 30-100 repos per page)
2. OAuth Permissions: Missing repository access permissions
3. Repository ID Format: Woodpecker requires numeric GitHub repository ID, not GraphQL node ID

Solution: Add Repository Manually via CLI

Step 1: Get GitHub Repository ID

# Get numeric repository ID (not GraphQL node ID)
gh api repos/SamyRai/turash --jq '.id'
# Output: 1103592817

Step 2: Add Repository to Woodpecker

# Use numeric ID (not R_kgDOQcd9cQ format)
woodpecker-cli repo add 1103592817

Step 3: Verify Repository

# List repositories
woodpecker-cli repo ls | grep turash

# Show repository details
woodpecker-cli repo show SamyRai/turash

Configure Harbor Registry

# Add Harbor registry
woodpecker-cli repo registry add SamyRai/turash \
  --hostname registry.bk.glpx.pro \
  --username admin \
  --password "nVbR0IZv02zdZaM1zqjOz8FVbdzmXlEUaOb59D5Bkz0="

Configure Secrets

# Add Docker credentials
woodpecker-cli repo secret add SamyRai/turash \
  --name docker_username \
  --value admin

woodpecker-cli repo secret add SamyRai/turash \
  --name docker_password \
  --value "nVbR0IZv02zdZaM1zqjOz8FVbdzmXlEUaOb59D5Bkz0="

Verify Configuration

# List registries
woodpecker-cli repo registry ls SamyRai/turash

# List secrets
woodpecker-cli repo secret ls SamyRai/turash

Understanding Repository IDs

GitHub Repository ID Formats

1. Numeric ID (What Woodpecker needs):

   gh api repos/OWNER/REPO --jq '.id'
   # Example: 1103592817
   

2. GraphQL Node ID (Not compatible):

   gh repo view OWNER/REPO --json id
   # Example: R_kgDOQcd9cQ
   

Why Sync UI May Not Show All Repos

1. Pagination: GitHub API returns repositories in pages (default 30 per page)
2. Private Repos: May require additional OAuth scopes
3. Rate Limiting: Too many repos can hit API rate limits
4. UI Filtering: UI may filter by active/inactive status

Best Practices

1. Add Important Repos Manually: Use CLI for critical repositories
2. Check OAuth Scopes: Ensure repo scope is granted for private repos
3. Use Sync for Discovery: Use UI sync to discover repos, then activate manually
4. Monitor Active Status: Only active repositories run pipelines

Troubleshooting

Repository Not Found (404)

# Check if repository exists in GitHub
gh repo view SamyRai/turash

# Verify numeric ID
gh api repos/SamyRai/turash --jq '.id'

# Try adding with numeric ID
woodpecker-cli repo add <numeric-id>

Can't Add Registry/Secrets

# Verify repository is active
woodpecker-cli repo show SamyRai/turash | grep ACTIVE

# Check repository ID format
woodpecker-cli repo show SamyRai/turash | grep ID

Sync UI Still Not Showing

1. Refresh Browser: Clear cache and refresh
2. Check Permissions: Verify GitHub OAuth token has repo scope
3. Use CLI: Add repositories manually via CLI (more reliable)
4. Check Logs: Review Woodpecker server logs for sync errors

Current Status

✅ Repository Added: SamyRai/turash (ID: 1103592817) ✅ Active: Yes ✅ Registry Configured: registry.bk.glpx.pro ✅ Secrets Configured: docker_username, docker_password

Repository is ready for CI/CD! 🚀