Issues, Labels, Milestones, Templates, Forms, Discussions, and Triage: Configuration, Design Choices, and Tradeoffs

1. Start with the uncertainty of the work, not with the coolest intake UI

A mature intake system does not force every thought through the same form. Highly repeatable bug reports benefit from required structured fields. Exploratory architecture conversations do not. A trusted maintainer may need an escape hatch for unusual operational work. The design question is: what evidence is mandatory before this class of work can enter the queue?

2. Free-form issue versus Markdown template versus issue form

Do not use required fields as a substitute for prioritization. A 20-field form can collect pristine data while discouraging reporters and delaying critical work. Every field should map to a triage decision: reproduce, classify impact, select owner, or choose next action.

3. Issue versus Discussion versus Pull Request

The cleanest lifecycle is often Discussion → decision → Issue → implementation branch → Pull Request → closure/reference. That sequence is not mandatory, but it prevents the PR from becoming the only record of why work exists and prevents Discussions from becoming an unactionable backlog.

4. Label taxonomy: optimize for filtering decisions, not completeness

Label explosion usually begins with good intentions: every nuance receives a tag. Soon bug, type:bug, kind:defect, and incident-ish all mean roughly the same thing. Query results become arbitrary because humans cannot apply the taxonomy consistently.

Before adding a label, write the query or routing rule that needs it. If no filter, dashboard, SLA, owner, or automation consumes the distinction, prose may be cheaper.

5. Milestones: bounded goals, not another label axis

A milestone groups issues and pull requests toward a repository-level goal and exposes progress. It is useful for a release, migration, audit remediation wave, or small timebox. It is less useful when used as a permanent “team” or “status” field. Those meanings belong in ownership or taxonomy, not a milestone that never completes.

6. Issue types and issue fields: organization-wide structure when it actually exists

Current GitHub supports organization-defined issue types such as Task, Bug, and Feature, and organization issue fields for structured metadata. These are not a reason to make the course dependent on an organization. A personal repository can achieve the chapter goals with labels, milestones, templates/forms, and assignees.

If your organization uses issue types, use them for stable cross-repository semantics and avoid duplicating the same concept as a label unless a compatibility reason demands it. Organization owners manage the type definitions; ordinary triagers should consume rather than redesign the classification system.

7. Chooser policy: make the intended path obvious but keep an operator escape hatch

A good config.yml can route bug reports into a form, questions into Discussions/support, and security reports into an approved private channel. Setting blank_issues_enabled: false reduces accidental free-form intake for Read/Triage contributors while GitHub currently preserves a maintainer-only blank option for Write/Maintain/Admin users. That balance supports both consistency and exceptional operator work.

8. Automation-assisted triage: observe first, decide carefully

Automation should reduce mechanical sorting while humans retain decisions where semantics or impact are uncertain. Later Actions chapters will implement permissions and events; here the design rule is to keep the mutation surface narrow and reversible.

9. Security and privacy shape intake design

Issue forms invite users to paste logs and screenshots. That creates a data-exfiltration path into public repositories. Ask for the minimum evidence, explicitly prohibit secrets/customer data, and route vulnerability reports to the repository’s security policy/private reporting process when applicable. A required “I removed secrets” checkbox is education, not enforcement.

Triage automation must also treat issue titles/bodies as untrusted input. Do not later interpolate issue text directly into shell commands in a workflow. Chapter 13+ will formalize this Actions boundary.

10. Worked decision table

11. Anti-patterns to reject during design review

• Every issue gets every label: classification stops carrying information.
• Milestone = status: use lifecycle/labels for state; milestones should complete.
• Form as interrogation: required fields that do not change a decision increase abandonment.
• Discussion as incident queue: operational ownership becomes ambiguous.
• Bot is the triage policy: automation implements policy; it should not silently invent it.
• Paid feature assumption: design a mandatory path that still works on a personal GitHub Free repository.

12. Design exercise: write your repository intake contract

1. Name three work kinds and define one sentence for when each applies.
2. Define priority criteria using impact, not adjectives in the report.
3. Choose one milestone use case and write its completion condition.
4. List the minimum fields needed to reproduce one bug class.
5. Write the boundary for Issue vs Discussion vs external incident channel.
6. Name one automated action you permit and one decision that must remain human.

13. Lesson summary

Good intake architecture minimizes semantic overlap. Use forms when structured evidence is genuinely required, labels for queryable repository-local distinctions, milestones for bounded goals, organization types/fields only when that governance exists, Discussions for conversation, and automation for reversible mechanics rather than opaque judgment.

Knowledge check

Authoritative references

• Configuring issue templates
• Syntax for issue forms
• Managing labels
• About milestones
• Managing issue types
• Managing issue fields
• About discussions
• Repository roles
• REST API endpoints for issues