Tracking work with GitHub Issues and Projects

GitHub Issues and Projects are two of the platform's core collaboration tools. Issues provide a shared space to capture tasks, bugs, and ideas before they slip through the cracks. Projects give you a visual dashboard for planning and prioritizing that work. Used together, they let a team coordinate progress and stay aligned on what matters next.

Creating an issue

An issue is the basic unit of work — anything from a bug report to a feature request. To practice creating one, open the sample repository at gh.io/gfb-issues and follow these steps:

  1. Click the Issues tab at the top of the page.
  2. Click the green New issue button in the top-right corner.
  3. Enter a clear title in the “Add a title” box.
  4. Add a description in the “Add a description” box. Include the expectations for whoever picks up the work: what behavior should be added or fixed?
  5. On the right side of the window, configure any relevant options:
    • Assignee: assign someone to the issue directly, including yourself.
    • Labels: categorize the issue using predefined or custom labels.
    • Type: mark the issue as a bug, task, or other type.
    • Projects: attach the issue to a project board.
    • Milestone: group the issue with a milestone.
  6. Click the green Create button below the description.

Once the issue exists, any team member can comment on it. Linking related issues is straightforward — type # followed by the issue number in a comment, and GitHub turns it into a clickable reference. When the work is finished, close the issue to signal that it's been addressed.

Setting up a project board

Projects organize issues onto a board you can customize to match your workflow. To create one from the sample repository:

  1. Click the Projects tab at the top of the page.
  2. Click the green New project button.
  3. Pick the Kanban template from the available options.
  4. Enter a name in the “Project name” field.
  5. Uncheck Bulk import items.
  6. Select Create project.

Your project opens with default columns, which you can rename or reorganize however you like. The tabs below the project name switch between different board views — explore them to see which layout suits your team.

To manage the project itself, click the three dots in the top-right corner and choose Settings. From there you can control access, create and edit custom fields, change the name and description, add a README, create a copy, and adjust visibility.

Customizing charts

Select the Insights button at the top of the window to view, create, and customize charts. Use the Configure button to change a chart’s layout via dropdown options.

Checking workflows

Next to the Insights button is Workflows. Built-in workflow rules let you automate status changes. For example, you can set an item's status to todo when it’s added to your project, close an issue when its project status changes, or set status to Done when an issue is closed.

Posting a status update

From the main project view, select Add status update at the top. This opens a window for adding a status report about your project's health and progress.

Syncing issues with a project board

Issues are individual tasks; projects are the dashboard that organizes them. To connect them, open your project board and select Add item at the bottom of the window. Click the plus icon and choose Add item from repository. Select the issues you want to bring in — use the checkbox at the top to select everything at once — then press Add selected items.

The issues appear as cards you can drag between status columns as work progresses. Click any card to see the full issue details. The two stay synchronized: change an issue's status in one place and it updates in the other automatically.

Walking through a real workflow

Here's how a typical team flow plays out once your board is connected:

  1. On your project board, click Add item at the bottom of the first column.
  2. Click the plus icon and select Create new issue.
  3. Enter a title and description for a new feature.
  4. Select Create, which adds the issue to the board immediately.
  5. Open the issue and apply the enhancement label under Labels.
  6. Assign the issue to a teammate using the gear icon next to “Assignees.”
  7. Add comments to the issue as work progresses.
  8. Open a pull request that addresses the issue. In the description, enter Closes # followed by the issue number. This links the PR to the issue automatically.
  9. Merge the pull request, which closes the issue.

This end-to-end flow keeps the team informed without constant status meetings. The issue records all context and conversation, and the board shows where everything stands at a glance.

For more detail, GitHub’s documentation on GitHub Issues and GitHub Projects covers the full feature set.