Principle:Kubeflow Kubeflow Issue Routing Configuration
| Knowledge Sources | |
|---|---|
| Domains | Issue Tracking, Contributor Onboarding, GitHub Configuration |
| Last Updated | 2026-02-13 00:00 GMT |
Overview
Issue routing configuration is the practice of directing contributor-filed issues to the correct sub-project repository using declarative GitHub issue template settings, ensuring each issue reaches the team responsible for that component.
Description
In a large, multi-repository open-source organization like Kubeflow, contributors frequently arrive at the top-level repository unsure of where to file bugs, feature requests, or questions. Issue routing configuration addresses this by using GitHub's native contact_links mechanism in .github/ISSUE_TEMPLATE/config.yml to present contributors with a structured list of sub-project repositories. By setting blank_issues_enabled: false, the configuration prevents unrouted issues from being filed in the umbrella repository, enforcing that all issues land in the appropriate component-specific tracker.
This principle applies broadly to any GitHub organization that maintains multiple repositories under a single project umbrella. The routing configuration acts as a declarative dispatch table: each entry maps a human-readable component name to the correct repository URL where maintainers can triage and respond. The pattern eliminates misfiled issues, reduces triage burden on umbrella repository maintainers, and improves contributor experience by providing clear, immediate guidance.
Usage
Apply issue routing configuration when:
- The project spans multiple repositories, each owned by different sub-teams or working groups.
- Contributors frequently file issues in the wrong repository due to the project's distributed architecture.
- The umbrella repository should not accept direct issue filings but instead serve as an entry point that redirects to component-specific trackers.
- You want to surface community resources (documentation, Slack channels) alongside issue routing options.
Theoretical Basis
The core logic of issue routing follows a declarative dispatch pattern:
- Disable blank issues: Setting
blank_issues_enabled: falseremoves the option to file a freeform issue in the umbrella repository, forcing contributors through the routing interface. - Present contact links: Each
contact_linksentry provides a name (the component or resource label), a url (the target repository's issue tracker or resource page), and an about description (a brief instruction directing the contributor). - Contributor decision: The contributor reads the list, identifies which component their issue relates to, and clicks the appropriate link to be redirected to the correct repository.
- Issue filed in correct location: The contributor files their issue directly in the sub-project repository, where component-specific maintainers can triage it with full context.
This approach relies on two key design decisions:
- Exhaustive coverage: The contact links list must cover all major sub-projects to avoid leaving contributors without a clear routing path. Kubeflow's configuration includes entries for Katib, KServe, Model Registry, MPI Operator, Notebooks, Pipelines, SDK, Spark Operator, Trainer, Dashboard, Profile Controller, and Manifests.
- Resource links alongside routing: Including documentation and Slack channel links in the same interface ensures contributors can find help even if their need is not an issue filing.