Quickstart for GitHub Discussions

Enable GitHub Discussions on an existing repository or organization and start conversations with your community.

In this article

Introduction

GitHub Discussions is a collaborative communication forum for the community around an open source or internal project. Discussions are for conversations that need to be transparent and accessible but do not need to be tracked on a project and are not related to code, unlike GitHub Issues. Discussions enable fluid, open conversation in a public forum.

Discussions give a space for more collaborative conversations by connecting and giving a more centralized area to connect and find information.

Enabling GitHub Discussions on your repository

Repository owners and people with write access can enable GitHub Discussions for a community on their public, internal and private repositories. The visibility of a discussion is inherited from the repository the discussion is created in.

When you first enable GitHub Discussions, you will be invited to configure a welcome post.

  1. On GitHub, navigate to the main page of the repository.

  2. Under your repository name, click Settings.

    Screenshot of the tabs in a GitHub repository. The "Settings" option is outlined in dark orange.

  3. Scroll down to the "Features" section and click Set up discussions.

    Screenshot of the "Discussions" option in the repository's settings. A green button, labeled "Set up discussions", is outlined in dark orange.

  4. Under "Start a new discussion," edit the template to align with the resources and tone you want to set for your community.

  5. Click Start discussion.

Enabling GitHub Discussions on your organization

Organization owners can enable GitHub Discussions for their organization.

When you enable organization discussions, you will choose a repository in the organization to be the source repository for your organization discussions. You can use an existing repository or create a repository specifically to hold your organization discussions. Discussions will appear both on the discussions page for the organization and on the discussion page for the source repository.

Permission to participate in or manage discussions in your organization is based on permission in the source repository. For example, a user needs write permission to the source repository in order to delete an organization discussion. This is identical to how a user needs write permission in a repository in order to delete a repository discussion.

You can change the source repository at any time. If you change the source repository, discussions are not transferred to the new source repository.

  1. On GitHub, navigate to the main page of your organization.

  2. Under your organization name, click Settings.

    Screenshot of the tabs in an organization's profile. The "Settings" tab is outlined in dark orange.

  3. Under "Discussions", select Enable discussions for this organization.

  4. Use the dropdown menu to select a repository to use as the source repository for your organization discussions.

  5. Click Save.

Welcoming contributions to your discussions

You can welcome your community and introduce a new way to communicate in a repository or organization by creating a welcome post and pinning the post to your GitHub Discussions page. Pinning and locking discussions helps people know that a post is meant as an announcement. You can use announcements as a way to link people to more resources and offer guidance for opening discussions in your community. For more information about pinning a discussion, see "Managing discussions."

Setting up community guidelines for contributors

For repository discussions, you can set contributing guidelines to encourage collaborators to have meaningful, useful conversations that are relevant to the repository. You can also update the repository's README to communicate expectations on when collaborators should open an issue or discussion. For more information about providing guidelines for your project, see "Setting up your project for healthy contributions."

For organization discussions, you share information about how to engage with your organization by creating an organization profile README. For more information, see "Customizing your organization's profile."

Creating a new discussion

Any authenticated user who can view the repository can create a discussion in that repository. Similarly, since organization discussions are based on a source repository, any authenticated user who can view the source repository can create a discussion in that organization.

  1. On GitHub, navigate to the main page of the repository or organization where you want to start a discussion.

  2. Under your repository or organization name, click Discussions.

    Screenshot of the tabs in a GitHub repository. The "Discussions" option is outlined in dark orange.

  3. On the right side of the page, click New discussion.

  4. Select a discussion category by clicking Get started.

    Screenshot of the "Select a discussion category" page. A button, labeled "Get started", is outlined in dark orange.

  5. Under "Discussion title", type a title for your discussion, and under "Write", type the body of your discussion.

    Screenshot of the text fields for the title and body for a new discussion.

  6. Click Start discussion.

Creating a new poll

Any authenticated user who can view a repository can create a poll. Similarly, since organization discussions are based on a source repository, any authenticated user who can view the source repository can create a poll in that organization.

  1. On GitHub, navigate to the main page of the repository.

  2. Under your repository or organization name, click Discussions.

    Screenshot of the tabs in a GitHub repository. The "Discussions" option is outlined in dark orange.

  3. In the list of categories, click Polls.

    Screenshot of the categories section in the "Discussions" tab. The "Poll" category is outlined in dark orange.

  4. On the right, click New discussion.

  5. Under "Discussion title", type a title and optionally, under "Write", type a body for your poll.

    Screenshot of the page to start a new poll.

  6. Under "Poll question", type a question for your poll.

  7. Under "Poll options", type at least two options for your poll.

  8. Optionally, to add an extra poll option, click Add an option.

    Screenshot of the page to start a new poll. The plus icon and "Add an option" are outlined in dark orange.

  9. Click Start poll.

Organizing discussions

Repository owners and people with write access to the repository can create new categories to keep discussions organized. Similarly, since organization discussions are based on a source repository, repository owners and people with write access to the source repository can create new categories for organization discussions.

Collaborators participating in and creating new discussions can group discussions into the most relevant existing categories. Discussions can also be recategorized after they are created. For more information, see "Managing categories for discussions."

To organize discussions more granularly, you can apply labels. For example, you can use labels to indicate the status of a discussion to make triaging more efficient. Each repository has one shared set of labels for issues, pull requests, and discussions. For more information, see "Managing labels."

Promoting healthy conversations

People with write permissions for the repository, or for the source repository for organization discussions, can help surface important conversations by pinning discussions, deleting discussions that are no longer useful or are damaging to the community, and transferring discussions to more relevant repositories owned by the organization. For more information, see "Managing discussions."

People with triage permissions for the repository, or for the source repository for organization discussions, can help moderate a project's discussions by marking comments as answers, locking discussions that are no longer useful or are damaging to the community, and converting issues to discussions when an idea is still in the early stages of development. For more information, see "Moderating discussions."

Next steps

Once there is a clear path to scope work out and move an idea from concept to reality, you can create an issue and start tracking your progress. For more information on creating an issue from a discussion, see "Moderating discussions."