Configuring the GitHub Issue Template Chooser¶

When you add issue templates to a GitHub repository, the "New Issue" button no longer opens a blank editor. GitHub replaces it with a chooser: a page that lists each template by name and description and, by default, includes a link that lets contributors skip the templates and open a blank issue. The chooser is useful on its own, but a small configuration file alongside your templates gives you considerably more control over what contributors see and where they can go.

The file, .github/ISSUE_TEMPLATE/config.yml, controls two things: whether blank issues are allowed, and whether additional links appear in the chooser that point contributors to discussions, documentation, or other resources.

This post covers how the file works, what options it supports, and how I use it across my own projects.

What Is the Issue Template Chooser?¶

When a repository has issue templates defined in .github/ISSUE_TEMPLATE/, GitHub replaces the default blank issue editor with a chooser page. The chooser lists each template and lets contributors pick the one that matches what they want to report. Without a config.yml, the chooser includes a link at the bottom that lets contributors skip the templates and open a blank issue anyway.

This default behavior is fine for repositories where unstructured issues are acceptable. For most projects, though, it creates a problem. Templates exist because structured input makes issues actionable. A bug report missing version numbers, reproduction steps, or environment details requires multiple back-and-forth exchanges before it can be investigated. Allowing contributors to bypass templates entirely undermines the value of having them.

The config.yml file lets you prevent that bypass and extend the chooser with links that route contributors to the right resource when none of the templates fit their situation.

The config.yml File¶

The file lives in .github/ISSUE_TEMPLATE/config.yml and supports two top-level keys:

blank_issues_enabled: false
contact_links:
  - name: Link Name
    url: https://example.com
    about: A short description of this link.

Both keys are optional and independent. A file that sets only blank_issues_enabled: false is valid, as is a file that defines only contact_links.

blank_issues_enabled¶

The blank_issues_enabled key accepts a boolean value. The default when no config.yml is present is true, which means contributors can bypass all templates and open a blank issue. Setting it to false removes that option from the chooser.

blank_issues_enabled: false

When this is set to false, the only way to open an issue is to use one of the defined templates. If a contributor's situation does not match any template, the contact_links you define give them somewhere constructive to go instead.

contact_links¶

The contact_links key accepts a list of external link objects. Each object has three required fields:

contact_links:
  - name: Discussions
    url: https://github.com/tenthirtyam/setup-task/discussions
    about: Need help with this GitHub Action? Ask a question in Discussions.
  - name: Task Documentation
    url: https://taskfile.dev
    about: Need help with Task in general? Check out the Task documentation.

Links appear in the chooser in the order they are listed. Each one renders as a distinct button with the name as the label and the about text below it. Contributors see all of the templates and all of the contact_links on the same page. The chooser is the one point where contributors decide what to do before they open an issue.

The url field accepts any valid URL. Common uses are:

• GitHub Discussions: Routes general questions and help requests away from the issue tracker and into a threaded forum where the community can participate.
• External documentation: Points contributors to the authoritative reference for the project, or for an upstream dependency, before they open an issue that the documentation already answers.
• Sponsor and support links: Gives contributors a way to support the project alongside the issue reporting flow.

Examples from My Repositories¶

The configuration varies across my projects depending on the community features each repository has enabled and what external resources are relevant.

A Minimal Configuration¶

Not every repository needs contact_links. When issue templates cover all contributor paths, the only configuration required is disabling blank issues:

blank_issues_enabled: false

That is the entire file. No contact_links are defined because every contributor need has a corresponding template. A contributor who wants to suggest a feature has a template. A contributor who found a bug has a template. There is no gap that needs a contact link.

Adding Sponsor and Support Links¶

For go-vnc, a Go library for the VNC client protocol, the configuration disables blank issues and adds two support links:

blank_issues_enabled: false
contact_links:
  - name: Sponsor this Project
    url: https://github.com/sponsors/tenthirtyam
    about: Support this project by sponsoring it on GitHub.
  - name: Buy Me a Coffee
    url: https://buymeacoffee.com/tenthirtyam
    about: Support this project by buying me a coffee.

The sponsor and support links are not part of the issue reporting flow; they are simply surfaced in the same place where contributors are already engaging with the project. Someone who came to open an issue sees the sponsorship options as a matter of course.

Linking to Discussions and External Documentation¶

For setup-task, a GitHub Action for setting up the Task task runner, the configuration is more complete:

blank_issues_enabled: false
contact_links:
  - name: Discussions
    url: https://github.com/tenthirtyam/setup-task/discussions
    about: Need help with this GitHub Action? Ask a question in Discussions.
  - name: Task Documentation
    url: https://taskfile.dev
    about: Need help with Task in general? Check out the Task documentation.
  - name: Sponsor this Project
    url: https://github.com/sponsors/tenthirtyam
    about: Support this project by sponsoring it on GitHub.
  - name: Buy Me a Coffee
    url: https://buymeacoffee.com/tenthirtyam
    about: Support this project by buying me a coffee.

This configuration covers three distinct contributor needs beyond issue templates.

Discussions handles the questions that do not belong in the issue tracker. A contributor who is not sure how to configure the action, or who wants to understand the behavior of an option, has a threaded forum for that. GitHub Discussions supports categories, upvoting, and marking answers as accepted, which makes it more appropriate for help requests than the issue tracker. Routing those conversations to discussions keeps the issue tracker focused on bugs and confirmed enhancement requests.

Task Documentation handles the upstream. A contributor who runs into something that looks like a bug might actually be encountering expected Task behavior that is documented at taskfile.dev. Linking directly to the upstream documentation from the chooser gives contributors the fastest path to an answer and reduces the volume of issues that turn out to be documentation questions about Task itself rather than issues with the action.

Sponsor and support links follow the same pattern as in go-vnc: they appear alongside the other links in the chooser, reaching contributors at a moment when they are actively engaging with the project.

Writing Your Own¶

A practical config.yml follows directly from the issue templates you have already defined. Start by auditing what each template covers and then ask: when none of these templates fit, where should a contributor go?

A few common patterns:

• If your repository has GitHub Discussions enabled, add a Discussions link. This is the most broadly useful addition for most open-source projects. It keeps general questions and help requests out of the issue tracker while still giving contributors a place to engage.
• If the project wraps an upstream dependency, link to that dependency's documentation. A significant share of issues in libraries and tooling wrappers are upstream questions in disguise. A direct link to the upstream documentation handles them before they become issues.
• If the project has a documentation site, link to it. Put it first in the contact_links list. Many contributors open issues for things that are already documented; surfacing the documentation in the chooser is a direct reduction in low-value issue volume.
• Add sponsor and support links last. They are important, but they are secondary to the resources that directly help contributors accomplish what they came to do.

Once you have identified the right links, disabling blank issues with blank_issues_enabled: false closes the gap. Contributors have structured templates for reporting and contact_links for everything else. There is no path to a blank issue that bypasses all guidance.

Putting It Together¶

The config.yml file in .github/ISSUE_TEMPLATE/ is compact, but it shapes the first decision every contributor makes when engaging with your issue tracker. The two keys, taken together, let you enforce structured issue reporting and direct contributors to the resources that actually help them.

The GitHub documentation on configuring issue templates covers the full specification. The file format is minimal, and the configuration takes under five minutes to put in place for any repository that already has issue templates defined.

A few structural notes:

• The file must be named config.yml, not config.yaml. GitHub only recognizes the .yml extension for this file.
• contact_links order matters. Links appear in the chooser exactly as listed in the file. Put the most relevant resources first.
• All three fields on each contact_link are required. GitHub will fail to render the chooser if name, url, or about is missing from any entry.
• The configuration applies repository-wide. There is no per-template override; the same config.yml governs the chooser for all templates in the repository.