GitHub Discussions
Discussions is a forum-style space that lives alongside Issues and PRs in a repo. It’s designed for open-ended conversation — questions, ideas, announcements, show-and-tells — the kind of threads that don’t map cleanly to “there’s a bug and someone needs to fix it”. For open-source projects, it’s the difference between a focused issue tracker and a sprawling, noisy one.
Discussions vs Issues
Aspect | Issues | Discussions |
|---|---|---|
Purpose | Trackable, actionable work | Open-ended conversation |
Closing state | Open / closed | Open (Q&A: marked as answered) |
Threaded replies | No — flat list of comments | Yes — nested replies |
Voting | Reactions only | Upvote button + reactions |
Categorisation | Labels | Categories |
Best for | Bug X needs fixing in v2.4 | "How do I configure SSL?" |
Enabling Discussions
Go to your repo’s Settings → General.
Scroll to the Features section.
Check Discussions and click Set up discussions.
GitHub seeds a few default categories you can rename or delete.
Default categories
Category | Format | Use for |
|---|---|---|
Announcements | Maintainer-only posts | Releases, deprecations, calls for testers |
Q&A | Question with answer marking | Support, “how do I…” |
Ideas | Open discussion + upvotes | Feature proposals before they’re issues |
Show and tell | Open discussion | Community projects built on yours |
General | Open discussion | Anything else |
Custom categories
You can create your own categories with any of the formats above. Common additions:
RFCs — proposed design changes, structured discussion.
Polls — built-in poll category for quick votes.
Roadmap — community-visible direction.
Help / Support — split out from Q&A for first-line triage.
Q&A: marking an answer
In a Q&A discussion, any reply has a Mark as answer button. Clicking it pins that reply to the top, marks the discussion as answered, and updates search filters so people can find solved questions. The original poster or a maintainer can mark answers.
Upvoting
Top-level posts have an upvote arrow. Use upvotes to signal “I want this too” without writing “+1”. Sort category views by upvotes to surface the most-wanted ideas.
Converting between Issues and Discussions
On an issue: Convert to discussion in the right sidebar. Useful when a bug report turns out to be a usage question.
On a discussion: Create issue from discussion to turn an idea into actionable work.
The original thread links to the new one in both directions.
Use cases
Community Q&A for OSS — replaces a flood of issues with “How do I do X?” questions.
Design discussions — proposing API changes, debating tradeoffs before a PR.
RFCs — community-style request-for-comments threads.
Release announcements — instead of an issue or a blog post.
Poll the community — built-in poll posts in dedicated categories.
Internal team discussions — for private repos: a lightweight forum without leaving GitHub.
Moderation tools
Pin discussions — up to 4 pinned per category.
Lock discussions — stop new comments without deleting.
Hide comments — collapse off-topic or abusive replies (reason recorded).
Block users — repo / org level.
Moderator role — non-maintainers granted moderation powers for community management.
Interaction limits — limit who can post (e.g. existing users only) during a brigading incident.
GitHub CLI
Discussions are still partly API-only
# List discussions (via GraphQL API)
gh api graphql -f query='
query {
repository(owner: "acme-co", name: "widget") {
discussions(first: 10) {
nodes { number title category { name } }
}
}
}'
# Create a discussion (POST via GraphQL — see GitHub docs)
gh api graphql -f query='...createDiscussion...'Linking from elsewhere
Reference a discussion in a PR or issue
Discussed in #42 — community wanted opt-in (see acme-co/widget#42 if cross-repo).
Common pitfalls
Categories sprawl — start with 4 or 5, add more only when there’s clear demand.
Mixed signals with Issues — write a CONTRIBUTING note explaining when to file an issue vs start a discussion.
Search invisibility — Discussions aren’t indexed by issue search; use the dedicated Discussions search.
Notification fatigue — watching the whole repo subscribes you to every discussion; tune to “Custom” → Issues / PRs only.