Now that you've signed up for Waffle and setup your account, it's time to start using your Waffle board!  This guide explains the basics of how to use a Waffle board.  If you need to create a new Waffle board, we have step by step instructions.

A Waffle board (also called a Waffle project) is associated with one or more repositories in GitHub.  A Waffle board is organized into columns, showing the progress of open GitHub issues and pull requests from those repositories.  You can add new issues directly from a Waffle board or in GitHub.  You can update issues on a Waffle board to make changes in GitHub.  Changes are automatically updated in real-time between GitHub and Waffle.  You can create multiple Waffle projects depending on how you and your team organize your code and work.

A Waffle board is organized by columns, which represent your team's workflow (from left to right).  

A common workflow used by teams is:

  • Inbox: New issues added in GitHub or Waffle are automatically added to the Inbox column.  This is a great place for new requests, ideas, and bugs.
  • Backlog: A place to keep issues that are good ideas but are being saved for later.
  • Next: The next most important issues that are ready to be worked on by by team members.
  • In Progress: Issues that are, well, in progress.  Normally used for active development.  Some teams create additional columns for design, testing, etc.
  • Review: Issues that have an open Pull Request that are being reviewed by other team member(s) to get feedback.  
  • Done: Issues that are done and shipped.  Depending on your team, this may also include finishing documentation, marketing, etc.

You can customize the columns on a Waffle board - adding, removing, and renaming them (from Settings > Columns).  Each column is either an Inbox, Progress, or Closed column.  Each Progress column is associated with a GitHub label.  Waffle uses labels assigned to issues and pull requests determine the column where they are display on a Waffle board.  You can apply labels in GitHub to automatically move cards on a Waffle board or you can drag a card on a Waffle board which will update the labels in GitHub.

(example of configuring column settings)

Creating Issues

It's easy to create new issues from a Waffle board.  To add a new issue, click New Issue (or use the i keyboard shortcut), add a Title, and click Add.  You can also assign labels to organize issues (ex. bug, feature request).  There are a few other optional fields that are covered in other help articles.

New issues are automatically added to the Inbox column unless you select a different column when creating the issue.  Note: If your board has multiple repositories, make sure the correct repository is selected before adding the new issue.  

(example of adding a new issue)

Moving Issues

As you and your team work on issues, you can drag and drop issues and pull requests across the board to show their current current status.  You can also easily add and change assignees depending on who's working on the issue or use WaffleBot to automatically assign you to the issue as you start work.  Waffle even supports multiple assignees if multiple team members are working on the same issue!

After completing issues, you can archive issues in Done columns using the archive button at the top of each column.  Archived cards are removed from your Waffle board.  Don't worry, you can still view archived cards.

(example of manually moving a card between columns)

Instead of manually updating Waffle, we recommend setting up WaffleBot which will automatically update and move cards for you based on your activity in GitHub.  WaffleBot updates over 100,000 cards a month helping developers to stay focused on their work.

Issues and pull requests are displayed as cards on your Waffle board.  Cards are updated in real-time from GitHub and other tools integrated with GitHub Status Checks such as Circle CI.  It's easy to see the status of pull request merges, pull request reviews, CI jobs, and deployments for each card.

(example of real-time status of pull requests, code reviews, and CI jobs on a card)

You can also click on a card to view and participate in discussions.

(example of a card's detail view)

Pro Tip: You can connect issues and pull requests to the same card so it's easy to see the status of work, even across multiple repositories.  Connected issues and pull requests move across a Waffle board together.


It's easy to filter a Waffle board to only view information that matters to you.  To filter your Waffle board, in the upper right of your Waffle board type text to filter for into filter box or click the filter icon to filter by other attributes such as assignee, label, and repository.

Filters are stored in the URL of your Waffle board, so it easy to bookmark or share a link to a filtered Waffle board.

Keep Learning!

Did this answer your question?