Quickstart for projects (beta)

Note: Projects (beta) is currently in public beta and subject to change.

Introduction

This guide demonstrates how to use projects (beta) to plan and track work. In this guide, you will create a new project and add a custom field to track priorities for your tasks. You'll also learn how to create saved views that help you communicate priorities and progress with your collaborators.

Prerequisites

You can either create an organization project or a user project. To create an organization project, you need a GitHub organization. For more information about creating an organization, see "Creating a new organization from scratch."

In this guide, you will add existing issues from repositories owned by your organization (for organization projects) or by you (for user projects) to your new project. For more information about creating issues, see "Creating an issue."

Creating a project

First, create an organization project or a user project.

Creating an organization project

On GitHub, navigate to the main page of your organization.
Click Projects.
Select the New project drop-down menu and click New project (Beta).

Creating a user project

On any GitHub page, click on your avatar, then select Your projects.
Select the New project drop-down menu and click New project (Beta).

Setting your project description and README

You can set your project's description and README to share the purpose of your project, provide instructions on how to use the project, and include any relevant links.

Navigate to your project.
Click to access the project settings.
To add a short description to your project, under "Add a description", type your description in the text box and click Save.
To update your project's README, under "README", type your content in the text box.
- You can format your README using Markdown. For more information, see "Basic writing and formatting syntax."
- To toggle between the text box and a preview of your changes, click or .
To save changes to your README, click Save.

You can view and make quick changes to your project description and README by navigating to your project and clicking in the top right.

Adding issues to your project

Next, add a few issues to your project.

When your new project initializes, it prompts you to add items to your project. If you lose this view or want to add more issues later, place your cursor in the bottom row of the project, next to the .

Type #.
Select the repository where your issue is located. To narrow down the options, you can start typing a part of the repository name.
Select your issue. To narrow down the options, you can start typing a part of the issue title.

Repeat the above steps a few times to add multiple issues to your project.

For more information about other ways to add issues to your project, or about other items you can add to your project, see "Creating a project."

Adding draft issues to your project

Next, add a draft issue to your project.

Place your cursor in the bottom row of the project, next to the .
Type your idea, then press Enter.
Click on the title of the draft issue. In the markdown input box that appears, enter the some more information about your idea, then click Save.

Creating a field to track priority

Now, create a custom field called Priority to contain the values: High, Medium, or Low.

To open the project command palette, press Command+K (Mac) or Ctrl+K (Windows/Linux).
Start typing any part of "Create new field".
Select Create new field.
In the resulting pop-up, enter Priority in the text box.
In the drop-down, select Single select.
Add options for High, Medium, and Low. You can also include emojis in your options.
Click Save.

Specify a priority for all issues in your project.

Example priorities

Grouping issues by priority

Next, group all of the items in your project by priority to make it easier to focus on the high priority items.

To open the project command palette, press Command+K (Mac) or Ctrl+K (Windows/Linux).
Start typing any part of "Group by".
Select Group by: Priority.

Now, move issues between groups to change their priority.

Choose an issue.
Drag and drop the issue into a different priority group. When you do this, the priority of the issue will change to be the priority of its new group.

Move issue between groups

Saving the priority view

When you grouped your issues by priority in the previous step, your project displayed an indicator to show that the view was modified. Save these changes so that your collaborators will also see the tasks grouped by priority.

Select the drop-down menu next to the view name.
Click Save changes.

To indicate the purpose of the view, give it a descriptive name.

Place your cursor in the current view name, View 1.
Replace the existing text with the new name, Priorities.

You can share the URL with your team to keep everyone aligned on the project priorities.

When a view is saved, anyone who opens the project will see the saved view. Here, you grouped by priority, but you can also add other modifiers such as sort, filter, or layout. Next, you will create a new view with the layout modified.

Adding a board layout

To view the progress of your project's issues, you can switch to board layout.

The board layout is based on the status field, so specify a status for each issue in your project.

Example status

Then, create a new view.

Click New view next to the rightmost view.

Next, switch to board layout.

To open the project command palette, press Command+K (Mac) or Ctrl+K (Windows/Linux).
Start typing any part of "Switch layout: Board".
Select Switch layout: Board.

When you changed the layout, your project displayed an indicator to show that the view was modified. Save this view so that you and your collaborators can easily access it in the future.

Select the drop-down menu next to the view name.
Click Save changes.