Documentation
Everything you need to know about using Reposignal as a contributor or maintainer.
Getting Started
Reposignal is an issue-first discovery platform that helps you find meaningful open source work without endless searching.
No account required
You can explore issues and repositories without signing in. Discovery is anonymous by default.
Create an account later if you want to save preferences and customize your discovery feed.
Start with issues
Unlike traditional platforms that show repositories first, Reposignal surfaces individual issues with full context.
See the work first, then learn about the project behind it.
Core principles
Issue-First
Focus on individual issues, not repositories or stars
Opt-In Only
Maintainers have complete control and explicit consent required
Privacy-Respecting
Anonymous discovery, private feedback
Calm by Default
Quiet, neutral interface with no gamification
For Contributors
How to discover issues, understand context, and start contributing to open source projects.
Discovering Issues
Browse the discovery feed
Visit the Discovery page to see curated issues from projects that have opted into the platform.
Filter by your interests
Use filters to narrow down issues by programming language, framework, domain, difficulty level, or issue type. Focus on work that matches your skills and interests.
Review issue context
Each issue shows essential information: repository name, tech stack, difficulty level (when available), issue type, and a direct link to the GitHub issue.
Click through to GitHub
Once you find something interesting, click to open the issue on GitHub. Read the full description, check the project's contribution guidelines, and comment to express interest.
Understanding Context
Every issue on Reposignal includes metadata to help you make quick decisions:
⚙️ Tech Stack
Primary programming languages and frameworks used in the project.
🏷️ Domain
Project focus area (web dev, CLI tools, data science, etc.).
📊 Difficulty
Maintainer-assigned difficulty level from 1 (easiest) to 5 (hardest).
🎯 Issue Type
Category such as bug, feature, docs, refactor, test, or infrastructure.
Providing Feedback
After your pull request is merged, you can optionally provide anonymous feedback about your experience.
Difficulty rating
Rate the actual difficulty you experienced (1-5). This helps maintainers calibrate their estimates for future contributors.
Responsiveness rating
Rate how responsive and helpful the maintainers were during your contribution (1-5).
Privacy guarantee: Your feedback is completely anonymous. We never store your GitHub identity with feedback submissions. Ratings are aggregated and used to improve the discovery experience for everyone.
For Maintainers
How to add your repository, manage issue visibility, and control when contributors discover your work.
Adding Your Repository
Install the GitHub App
Install the Reposignal GitHub App on your repositories. You control which repositories are included—install on specific repos or all of them.
Go to setup page →Complete the onboarding
After installation, you'll complete a one-time setup where you can configure repository settings, set discovery visibility, and customize your project description.
Start classifying issues
Use slash commands on GitHub to classify issues with difficulty levels, types, and visibility settings. Only classified issues appear in discovery.
Repository Settings
Control how your repository appears in discovery and when contributors can find it.
🌐 Discovery Visibility
Public: Your issues appear in discovery feeds for all users
Paused: Temporarily hide from discovery (useful during feature freezes or heavy development periods)
Off: Never appear in discovery (repository stays tracked but hidden)
📝 Project Description
Customize how your project is described to potential contributors. This appears alongside your issues in discovery.
🏷️ Metadata
Languages, frameworks, and domains are automatically detected by the Reposignal bot. You can review and adjust these in your repository settings.
Viewing Analytics
Access aggregated feedback and statistics to understand how contributors experience your project.
Difficulty calibration
See how your difficulty estimates compare to contributor experiences
Responsiveness scores
Aggregated ratings of maintainer responsiveness
Contribution patterns
Understand which types of issues attract the most interest
Audit logs
Complete immutable history of all changes to your repository settings
Slash Commands
Use slash commands directly in GitHub issue comments to classify issues and manage visibility.
Maintainer Commands
Available to users with write, maintain, or admin permissions on the repository.
/reposignal difficulty <1-5>maintainerSet issue difficulty level from 1 (easiest) to 5 (hardest).
Example: /reposignal difficulty 3
This helps contributors understand the complexity before diving in. Be honest—it builds trust.
/reposignal type <type>maintainerSet issue type to categorize the work.
Valid types:
docs — Documentation updates
bug — Bug fixes
feature — New features
refactor — Code refactoring
test — Test additions/updates
infra — Infrastructure work
Example: /reposignal type bug
/reposignal hidemaintainerHide specific issue from discovery.
Use this for issues that aren't ready for external contributors, are on hold, or require internal context.
/reposignal showmaintainerShow previously hidden issue in discovery.
Make a hidden issue visible again when it's ready for contributors.
Note: Commands and confirmation messages auto-delete after 1 minute to keep issue threads clean. You can use multiple commands in the same comment.
Contributor Commands
Available to PR authors after their pull request has been merged.
/reposignal rate difficulty <1-5>contributorRate the actual difficulty you experienced.
Example: /reposignal rate difficulty 4
Your feedback helps maintainers calibrate difficulty estimates for future contributors.
/reposignal rate responsiveness <1-5>contributorRate maintainer responsiveness.
Example: /reposignal rate responsiveness 5
This feedback helps the community understand what to expect when contributing.
Privacy: All contributor feedback is completely anonymous. Your GitHub identity is never stored with feedback submissions. Ratings are aggregated and used to improve the platform.
Upcoming Features
The following features are currently in development and will be available soon.
Repository Visibility Controls
Coming SoonEnhanced commands to manage your repository's overall visibility and discovery settings.
Overall visibility toggle
Control whether your entire repository appears in discovery with a single command
Temporary opt-out
Pause discovery during feature freezes, heavy development periods, or when you need to focus on existing contributors
Permanent opt-out
Remove your repository from Reposignal entirely while maintaining your historical data and settings
Rating System Controls
Coming SoonChoose whether to enable contributor feedback and ratings for your repository.
Enable/disable ratings
Turn contributor feedback on or off based on your preferences and community management style
Granular feedback control
Choose which types of feedback to collect (difficulty ratings, responsiveness, etc.)
Unclassified Issue Management
Coming SoonBetter tools for managing issues that haven't been classified yet.
Bulk classification
Classify multiple issues at once with batch commands
Classification reminders
Optional notifications for new issues that need classification
Default visibility for unclassified
Set whether unclassified issues should be hidden or visible by default
Stay updated: These features are actively being developed. Follow our GitHub organization for the latest updates and release announcements.
Feedback System
How anonymous contributor feedback works and why privacy matters.
How It Works
Post-merge only
Feedback commands only work after your pull request is merged. This ensures you've completed the contribution and can provide informed feedback.
One-time submission
You can provide feedback once per merged pull request. This prevents duplicate submissions and maintains data integrity.
Anonymous by design
Your GitHub identity is never stored with feedback. The system logs that feedback was received, but not who submitted it.
Aggregated statistics
Feedback is aggregated into repository-level statistics. No individual feedback is ever displayed publicly.
Why Privacy Matters
We intentionally designed the feedback system to be anonymous because:
Honest feedback
Contributors can share their true experience without fear of retaliation or judgment.
No contributor tracking
We refuse to build reputation systems that rate individuals. Contribution is collaborative, not competitive.
Focus on improvement
Aggregated data helps maintainers improve their onboarding and issue classification without singling out individuals.
Architecture
Understanding how Reposignal works behind the scenes.
Three-Repository System
Reposignal consists of three separate repositories that work together:
reposignal-backend
Bun + Hono + Drizzle ORM + PostgreSQL
Single source of truth for all data.
• GitHub OAuth authentication
• Repository and issue management
• Discovery engine with filtering
• Analytics and statistics
• Immutable audit logging
reposignal-frontend
Next.js 16 + TypeScript + Tailwind CSS 4 + Zustand
User interface for discovery and management.
• Anonymous-first design
• Issue discovery and browsing
• Repository exploration
• User profile management
• Dark mode native
reposignal-app
Probot (Node.js) + BullMQ + Redis
GitHub App for event handling and repository monitoring.
• Receives GitHub webhooks
• Processes slash commands
• Syncs repository and issue data
• Manages bot message cleanup
• Handles anonymous feedback
Key Design Principles
Backend owns all state
The bot has zero persistent state. It only calls backend endpoints. Frontend never calls bot endpoints.
Immutable logging
All state changes are logged permanently. Logs explain what happened, not who to judge.
Separation of concerns
Backend handles data, bot handles GitHub interactions, frontend displays information.
API Reference
Available API endpoints for programmatic access to Reposignal.
Public Endpoints
No authentication required.
/public/discoveryBrowse issues with filtering support
/public/repositories/:idGet repository details and metadata
/public/repositories/:id/issuesList issues for a specific repository
/public/repositories/:id/statsGet aggregated repository statistics
Metadata Endpoints
Get canonical taxonomy data.
/meta/languagesList all supported programming languages
/meta/frameworksList all supported frameworks and libraries
/meta/domainsList all project domains and categories
Complete Documentation
View the complete API documentation with request/response schemas and examples.
View OpenAPI Documentation↗Local Development
Set up Reposignal locally for development and testing.
Prerequisites
Node.js 20 or higher
Bun (latest version)
PostgreSQL 14 or higher
Redis 6 or higher (for bot)
Git
GitHub account
Setup Order
Follow these steps in order to set up the complete Reposignal development environment.
Create GitHub Apps
Create a GitHub App (for the bot) and a GitHub OAuth App (for user authentication). Save the credentials for environment configuration.
Set up Backend
Clone reposignal-backend, install dependencies, configure environment variables, and run database migrations.
Set up Frontend
Clone reposignal-frontend, install dependencies, and configure environment variables.
Set up Bot
Clone reposignal-app, install dependencies, set up Smee.io for webhook proxying, and configure environment variables.
Repository Links
Last updated: