Skip to main content
GitHub Discussions provide a structured forum for repository communities to have broader conversations that don’t fit into issues or pull requests. Use Discussions for brainstorming, Q&A, polls, announcements, and showcasing work.
Use Discussions for general conversation, brainstorming, polls, Q&A, and announcements that don’t fit as issues or pull requests.

​
What you’ll do in this lesson

  1. Open the repository (example: block-buster) with an account that has repository settings access (example user: AZ-1000).
  2. Enable Discussions from the repository Settings.
  3. Create the first discussion and choose an appropriate category.

​
Quick prerequisites

  • You must have repository settings access (Admin or maintain) to enable Discussions.
  • Discussions are enabled per-repository; enabling in one repo does not enable them across an organization.
You need repository-level settings access to enable Discussions. If you don’t see the Discussions option in Settings, confirm your permission level or contact a repository admin.

​
Step 1 — Open repository and enable Discussions

  1. Open your repository (for example block-buster) and sign in with an account that has repository settings access (e.g. AZ-1000).
  2. Go to Settings → scroll to the Discussions section to enable it and configure defaults.
After enabling, you can immediately create the repository’s first Discussion.
The image shows the GitHub interface for starting a new discussion in the "block-buster" repository. It includes fields to add a discussion title and body, along with sample text and guidelines.
When creating a discussion, GitHub shows a starter screen with a title and suggested body text. You can accept the defaults or customize the title, body, and labels. By default the first discussion is often posted to the Announcements category unless you choose another category (this default can vary by repository configuration).

​
Discussion categories and when to use them

GitHub provides built-in categories so you can organize conversations by intent. Choose the category that best fits the content of your post.
The image shows a GitHub page where users can select a discussion category, with options like Announcements, General, Ideas, Polls, Q&A, and Show and tell. Each category has a "Get started" button.

​
Step 2 — Create and publish the discussion

  • Select the appropriate category (for this example, choose Announcements).
  • Enter a clear title and body. Use formatting, code blocks, and links to make the post useful and searchable.
  • Submit the discussion. After the first discussion is created, a Discussions tab appears in the repository navigation bar.
The image shows a GitHub Discussions page titled "Welcome to block-buster Discussions!" with confetti animation, indicating the creation of the first discussion in a repository.

​
Managing discussions

Once created, discussions behave similarly to issues and include moderation and management features:
  • Pin important or featured discussions to keep them prominent.
  • Lock conversations to prevent further replies when necessary.
  • Convert or transfer a discussion to an issue for actionable items.
  • Edit content and adjust labels or categories as needed.
  • Use moderation tools to flag or remove inappropriate posts.

​
Best practices and tips

  • Choose clear, descriptive titles to improve discoverability.
  • Use categories consistently so users can find content quickly.
  • Encourage maintainers and community members to respond and close conversations when resolved.
  • Convert long-running proposals or actionable items into issues to track implementation.
Advanced moderation and detailed category configuration are important topics on their own and can be explored in separate lessons.

Watch Video