Triavo Documentation

Last Updated: March 17, 2026

Triavo is a GitHub-integrated developer tool that recommends issue assignees and provides AI-assisted repository insights by combining GitHub activity signals, semantic search, and ranking logic.

Product Overview

• Triavo listens to selected GitHub webhook events.
• On new issues, Triavo computes a recommended assignee.
• On push events, Triavo stores commit message embeddings for semantic search.
• Triavo can apply assignment after a maintainer comment command: /triavo assign.

How Triavo Works

Triavo builds a living understanding of each connected repository by learning from recent commits, issues, pull requests, and contributor activity. That project context is then reused whenever new work appears.

• When a repository is connected, Triavo ingests recent project history and turns the text into searchable semantic knowledge.
• As fresh development activity comes in, Triavo updates that knowledge so its suggestions stay aligned with the latest code changes.
• When a new issue is opened, Triavo first checks whether the report matches an existing issue through semantic similarity and near-exact wording.
• If the issue is new, Triavo scores possible contributors using semantic relevance, recent activity, contribution history, expertise overlap, and current workload.
• Triavo stores suggestion history so maintainers can review the latest recommendation and act on it later.
• If the issue appears to be a duplicate, Triavo redirects discussion to the original issue, can highlight a likely contributor on that issue, and closes the duplicate to keep the tracker cleaner.

Core Architecture

• API service (FastAPI): Receives webhooks, verifies signatures, orchestrates background tasks, and serves status/landing/docs pages.
• PostgreSQL (Neon or compatible): Stores issue suggestion history and webhook delivery deduplication records.
• Qdrant: Stores vector embeddings and commit payload metadata for similarity matching.
• GitHub API: Provides repository metadata, contributors, commits, pull requests, and issue/comment operations.
• AI model/embedding providers: Process issue and commit text to generate semantic vectors and insight signals.

Supported GitHub Events

• issues with action opened: triggers assignee recommendation workflow.
• issue_comment with action created: processes /triavo assign command.
• push: stores new commit embeddings for future similarity queries.

End-to-End Flow

• GitHub sends a webhook payload to /webhook.
• Triavo validates X-Hub-Signature-256 with WEBHOOK_SECRET.
• Triavo deduplicates deliveries using X-GitHub-Delivery.
• For issues.opened:
• Triavo fetches contributors, recent commits, and recent PRs via GitHub API.
• Triavo computes baseline, semantic, expertise, and workload-adjusted scores.
• Triavo stores the top suggestion in PostgreSQL.
• Triavo posts a recommendation comment on the issue.
• For issue_comment.created with /triavo assign:
• Triavo retrieves the latest stored suggestion.
• If assignable, Triavo calls GitHub API to assign the suggested user.
• For push:
• Triavo extracts valid commits.
• Triavo stores commit-message embeddings and metadata in Qdrant.

Security Controls

• HMAC signature verification for all webhook payloads.
• Unique delivery tracking to prevent duplicate processing.
• Secret-based authentication to infrastructure providers.
• HTTPS/TLS expected in deployment environments.

Retention and Maintenance

• Webhook delivery deduplication records are cleaned on a scheduled interval.
• Default webhook delivery retention is 30 days (configurable).
• Backups/restores should include PostgreSQL and Qdrant state.
• Monitor logs and /health/ready for operational status.

Operational Troubleshooting

• 403 on webhooks: Verify WEBHOOK_SECRET matches GitHub App webhook configuration.
• No suggestions posted: Confirm GitHub App installation permissions and repository access.
• Readiness failing: Check database/Qdrant connectivity and credentials.
• Assignment command not working: Ensure /triavo assign comment is exact and suggested user is assignable.

Contact and Support

• Support Email: [email protected]