What is GitHub Discussions? A complete guide

What’s inside

Getting started with GitHub Discussions: How to enable GitHub Discussions in your repository and popular use cases.
Best practices for using GitHub Discussions: Key tips on how to use GitHub Discussions successfully as a community engagement tool.
GitHub Discussions vs. GitHub Issues: When to use each: When and how to use Discussions and Issues on a project—and how to turn a Discussion into an Issue (and vice versa).

Building great software involves more than just the source code. If you have a growing community, there’s so many other things that may occupy your time. There’s roadmap planning, working with your community on potential features, succinctly sharing progress updates with collaborators, attracting and onboarding new contributors, and more.

All of these things can be solved with a central gathering space where maintainers and contributors can all get together to capture ideas, converse, and plan for the future.

The answer? GitHub Discussions. Launched in 2020, Discussions brings community forums to GitHub making it easier for open source communities, developer teams, and companies to ask questions, share ideas, and build connections with each other — all right next to their code.

In this guide, we’ll explore GitHub Discussions, including how to use it, best practices, and how it complements other GitHub features (like Issues) to support the full developer experience.

Getting started with GitHub Discussions: The basics

Designed for any developer community working on something together, GitHub Discussions offers a big benefit: It lives directly in your repository (aka, right where you’re already working and where your community is), reducing the context-switching that comes with managing third-party forums on other websites.

It also gives you an asynchronous communication platform that allows for open-ended conversations, making it easier to save historical information, frequently asked questions, and feature ideas.

How to enable GitHub Discussions in your repository

Discussions can be enabled in any public or private repository by an admin, maintainer, or anyone with write access. Here’s how:

Open your repository settings and go to “Features”
Check the box next to “Discussions”
Create a welcome post to start your forum

It’s that simple. Don’t believe us? Here’s proof 👇.

A GIF showing a GitHub user enabling Discussions in their repository.

Learn more about getting started with Discussions

What you can do with GitHub Discussions: Examples of common use cases

Discussions gives you the ability to directly engage with your communities and collaborators, all while staying on GitHub. To help facilitate, it also provides features like labeling, marking helpful answers, upvoting, and more.

Here are some ways open source communities and teams are using GitHub Discussions:

Create community announcements: Whether you’re an admin, maintainer, or contributor, you can use Discussions to make community announcements about upcoming releases, roadmap decisions, and more. Need proof? Check out how the open source community Node announced its roadmap to its community.
Share ideas and get community feedback: Maybe you need feedback on a problem you’re trying to solve. Or maybe you want to share ideas about new features you want to see as part of a future sprint. Discussions is designed to make community engagement simple and collaborative—and a popular use case among open source communities and teams is using it to share ideas and get feedback (take a look at how the open source community Gatsby did just this).
Discuss a new release: Some open source communities use Discussions to answer questions about a new release from their wider communities—that’s something we’ve seen to great effect from the React team, which used Discussions to field questions about its latest release (and explain a little more about what that release does, too).
Spotlight important conversations by pinning them: Discussions supports pinning conversations and announcements to the top of the feed which makes it easy to make sure your community or team has access to important information. A great example of this in action comes from the Next.JS community, which pins important and helpful conversations to the top of its Discussions board.
Determine hot topics in your community: You can sort all conversations in a given Discussions instance by how many upvotes they’ve received—and you can do this by day, month, year, or all time. This is a great way to keep track of what conversations are triggering the most interest in your community.
Ask questions and get answers with Q&A posts: Have a question about a pull request, issue, or problem you’re confronting? Try posting a Q&A discussion to find an answer. And the best part: You can mark which responses are helpful answers so other people can quickly find out what helped you most. Want an example? Try checking out the jsPsych community Discussion board, which features a number of Q&A posts (with helpful answers marked).
Coordinate engineering resources: Another popular use case for Discussions among some communities is coordinating team resources and sprint planning. Not only that but you can create and assign Issues directly from your discussion, which makes it easy to plan sprints (more on this in a bit).
Hold general discussions: You can use Discussions to talk shop (or life) with general posts to engage your community or team. For instance, the Next.JS community uses Discussions to showcase what companies and websites are using its software.

Best practices for using and moderating GitHub Discussions

Discussions gives you a community forum right in your repository, making it easy to communicate with collaborators and foster community—all right from GitHub.

But we all know that successful forums need moderation to make sure the conversation stays productive and helpful. Whether you’re using Discussions for a small team or as part of a large open source project, here are some best practices to keep in mind:

Use labels to keep your spaces organized. Discussions supports labels, which you can customize to fit your needs. These labels can be applied to any discussion and can be used to surface important information, make searching for a specific discussion easier, and help avoid duplicative content.
In Q&A discussions, mark which reply answers the question. A popular use case of Discussions is Q&A posts, which can be helpful to crowdsource an answer from your team or community. But when you ask a question, be sure to mark which reply answered your question. This can help you avoid duplicative content (or necro posting). It’s also a good practice to upvote any comment or reply that’s helpful or accurate.

A picture showing an answer that has been marked as helpful in a GitHub Discussions thread.

Use Discussions to trigger automations: Discussions supports the GraphQL API—and that means you can use GitHub Actions to trigger automations off of new Discussions and comment events. Popular use cases include triggering chat app notifications when a new Discussion or comment is created, and sending automatic updates to websites with key Discussions such as announcements.
Turn collaborators into moderators and assign them triage permissions. If your community is big enough, you’ll be well served by turning a number of collaborators into moderators to help you keep your Discussions instance running smoothly. You can do this by assigning triage permissions to people in your project. This turns them into moderators who can mark answers, manage the forum, remote content, and more.
Use the top sort feature to find trending conversations. Once a Discussions forum gets big enough (here’s looking at you Next.JS), you’ll likely find a lot of day-to-day activity and plenty of posts. If you don’t have time to go through every conversation, you can look at the top trending conversations by selecting the top sort feature and setting it to your preferred time frame (day, week, month, year, or all).

A picture showing an answer that has been marked as helpful in a GitHub Discussions thread.

GitHub Discussions vs. GitHub Issues: When to use each

A common question among developers new to GitHub Discussions goes something like this: When should I use Discussions and when should I use Issues?

The short answer: Discussions are great for questions and ideas that require team communication to make a decision, while Issues are defined pieces of work.

The slightly longer answer: In any given project or sprint, you have things you need to discuss and those you need to do. Discussions are for—no surprise here—discussing things. Issues are for cataloguing the work you need to do after you’ve reached a decision about how to move forward.

When to use GitHub Discussions

GitHub Discussions is best suited as a tool to share questions, ideas, conversations, requests for comment (RFC), resource planning, and announcements.

When to use GitHub Issues

GitHub Issues are used to track executable pieces of work with a defined start and end point. These can include new features, fixing bugs, general updates, and tracking for epics and sprints, among other things.
Both Issues and Discussions can help you be more productive and collaborative. But when they’re used together, you can be more efficient by reserving Issues and pull requests for active work and Discussions for conversations, questions, and community engagement.

And there’s another benefit: You can reference a discussion in an issue, which can help provide background and context for a piece of work. You can also convert an issue into a discussion if you need additional information and decisions before a task can be completed.

How to create an issue from a Discussion

Discussions offers an asynchronous communication platform that saves historical information, notes, ideas, and more. The best part: You can create an issue directly from a discussion, which means you can attach your notes and decisions that led to a piece of a work directly in an Issue.

To do this, go to the right sidebar and click Create issue from discussion and then build out your issue and assign it to someone (or yourself).

How to convert an issue into a discussion

Let’s be honest: Sometimes people use issues as a default bucket for anything that is a conversation—or doesn’t have an executable task involved. Other times, people will create an issue and then realize they need a team decision before they can start moving forward.

In this case, you can convert an issue into a discussion by going to the bottom right corner of the issue and selecting “Convert to discussion.”

Doing this will close and lock the issue while preserving the title, description, and author for the new discussion.

Take this with you

Whether you’re planning for a feature roadmap, asking questions about something you’re working on, or engaging with an open source community that’s building software you use, GitHub Discussions offers a central space for all communities—both open source and private—to connect and collaborate.

Discussions is designed to do three things:

Provide a centralized community space for conversations and questions (and make the lives of maintainers easier when it comes to Issues and pull requests)
Create a place for newcomers and non-code collaborators to participate in a larger community
Highlight project contributors to help develop the next generation of maintainers

Try enabling it today in your public or private repositories—or engaging with any number of open source communities you’re interested in learning more about.