Create a home for your community with GitHub Discussions

Incorporating new technology into your organization’s workflow involves more than just understanding the tool—it requires a culture shift towards community. By creating a destination for inspiration and knowledge sharing, you can enable your teams and individuals to accomplish more together.

GitHub Discussions is a dedicated space for conversations. It decreases the burden of managing active work in issues and pull requests by providing a separate space to host ongoing discussions, questions, and ideas. We use GitHub Discussions to enable dialogue among tens of thousands of community members via the GitHub Community Discussions, to host a private GitHub maintainers community, and to support team-internal conversations.

We created GitHub Community-in-a-box, packaging up tooling, resources, and knowledge, for organizations of all sizes, to enable our customers to build internal communities of learning at scale using GitHub Discussions.

Let’s take a look at ways to manage GitHub Discussions for your community, best practices for moderation, tips for promoting healthy engagement and content creation, and ideas for going the extra mile for your community.

When might GitHub Discussions be useful for you?

You can use GitHub Discussions to chat about big-picture ideas, brainstorm, and develop a project’s specific details before committing it to an issue, which can then be scoped. GitHub Discussions is useful for teams in a number of scenarios:

• You are in the discovery phase of a project and are still learning which direction your team wants to go in.
• You want to collect feedback from a wider community about a project.
• You want to keep bug fixes, feature requests, and general conversations separate.
• You want to measure interest in new ideas and gauge community opinion using polls.

To learn more about GitHub Community-in-a-box and get started with GitHub Discussions, check out this guide, download our community checklist, and don’t miss GitHub Community Discussions Announcements to keep up with new features, events, beta programs, surveys, and more!

Managing a successful GitHub Discussions community

Based on what we’ve learned through our community, we have a few recommendations that will help yours thrive:

1. Grant helpful community members moderator or maintainer permissions to help drive a healthy community, as well as moderate and guide your community space.

2. Create categories.

Think about the topics your community will likely discuss and group them into the most relevant categories. This will ensure your community stays neat and organized. GitHub Discussions come with a few default categories:

But it takes seconds to set up additional ones, as you can see in the example below:

3. Leverage GitHub Discussions category forms.

You can encourage community members to include specific, structured information in their discussions by using discussion forms in your repository. Let’s make a basic category form for our Knowledge base category we created in the last step:

Once you commit the change and start a new discussion for the Knowledge base category, you will see your category form in action:

4. Create + add labels to discussions to organize them more granularly.

This will enable your community to filter by relevant labels and will also create more meaningful data insights for your community. Similar to categories, GitHub Discussions comes with a set of default labels:

But let’s create a few additional ones that meet our community’s needs:

5. Pin important discussions.

You can pin a discussion for the repository as I have done here with my GitHub Discussions resources post:

Or to a specific category:

The globally pinned discussions will be shown in addition to the discussions pinned to a specific category.

Deep dive: GitHub Discussions moderation

Moderation of a community is incredibly important to the overall community health (see the GitHub Docs for detailed guidance). The following best practice tips will help you maintain an active and healthy community:

1. Reply to posts in assigned categories.

Replying to questions and comments within a reasonable amount of time (such as in this example) is important to ensure community members find value in your discussions instance, and will encourage them to return and actively contribute to your community. In order to manage the workload we recommend assigning dedicated moderators per category depending on the new discussions volume created per day.

2. Mark comments as answers.

If a question has been resolved, mark the best comment as an answer (see the below example from the GitHub Community Discussions).

This will aid community members in finding solutions to their questions and will motivate contributions as community members with the highest number of marked answers will appear in the “Most helpful” leaderboard of your GitHub Discussions community.

3. Manage spam.

Spam is unlikely to occur in an internal community, however, it may happen that community members post comments that are off-topic or engage in heated discussions. We recommend you warn offenders and hide their discussions. In cases of repeat abuse, you may want to consider blocking someone from your community completely.

We recommend adding a Code of Conduct to define community standards, signal a welcoming and inclusive project, and outline procedures for handling abuse. When you add a Code of Conduct like the Contributor Covenant Code of Conduct to your repository, it will automatically be linked in your discussions instance as well once you commit the file.

You may want to consider creating other community health files depending on your specific needs.

4. Lock or unlock discussions.

This is a valuable feature for scenarios when you want to keep a discussion in your community in “read-mode” only but don’t want to enable community members to leave further comments (for example, you requested feedback for a feature but collected enough information). Have a look at this post from the GitHub Community Discussions for reference:

5. Edit or delete comments.

You have the option to edit or delete comments in case community members post inappropriate content or confidential information.

6. Recategorise posts.

Community members may accidentally post discussions in the wrong category. To keep your community clean and tidy, we recommend you move posts to the correct category.

7. Apply labels.

We recommend creating a variety of labels with regards to the format (for example,question, feature request, bug report, feedback) as well as topic (for example, GitHub Actions, GitHub Copilot, GitHub Codespaces) of discussions within your community. The ability to filter by labels will ease moderation, help community members find the right answers, and enhance the data you collect. To gain inspiration, take a peek at the labels we use in the GitHub Community Discussions.

Going the extra mile

In the section above we described the basics of community management. If you want to take it a step further and provide the best experience for community members, here are a few more suggestions:

1. Welcome new community members

When someone new joins your community, make an effort to send them a personal welcome message. You can even start an “Introduce Yourself” thread (tip: pin the thread globally or in the right category) for community members to post little paragraphs about themselves and to make their first discussions contribution as easy as possible.

2. Look for community members who are actively participating and posting great answers— appreciate and motivate them.

Each community has certain members who go above and beyond to be helpful to others. They are the pillars of your community. To help retain your top contributors and to keep them motivated, show them some love. You can do so for example by highlighting them in a discussions post. The Most helpful leaderboard will show your community’s top contributors over the past 30 days:

3. Analyze your GitHub Discussions data and determine trending topics.

Use Discussions insights to understand the contribution activity, page views, and growth of your discussions community. In addition, you can see what is most popular in your categories and track the top viewed posts every week. This information can help you craft content based on topics community members seem to struggle with or are most interested in.

4. Create content to generate engagement and enhance your community knowledge base.

Consider crafting monthly check-ins, AMAs (Ask Me Anything), product update announcements, or blog posts written by subject matter experts.

GitHub is a community of communities, including yours.

We hope these resources help you build and manage your own online communities using GitHub Discussions!

Additional resources for launching and managing your own GitHub Discussions community

• 4 ways your discussions categories can be better optimized
• How five open source communities are using GitHub Discussions
• 7 unique software collaboration features in GitHub Discussions
• Metrics for issues, pull requests, and discussions
• GitHub Community Programs

Written by

Anna Ossowski

@ossanna16