Quickstart for Projects

Introduction

This guide demonstrates how to use Projects to plan and track work. In this guide, you will create a new project, customize views, and add custom fields to manage a team backlog, iteration planning, and a team roadmap to communicate priorities and progress with your collaborators. You'll also set up built-in workflows to automatically manage the items in your project and charts to visualize items in your project.

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 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

1. In the upper-right corner of GitHub, click your profile picture, then click Organizations.

2. Click the name of your organization.

3. Under your organization name, click Projects.

   

4. Click New project.

5. Select which type of project or template you want to use.

   • To create a blank project, under "Start from scratch," click Table, Roadmap, or Board.
   • To create a project from a template, click the template you want to use. You can select from the built-in templates curated by GitHub, the templates created by your organization, and the recommended templates that have been chosen by your organization.

6. Optionally, if you selected a template, review the fields, views, workflows, and insights that will be created.

7. In the text box under "Project name," type a name for your new project.

8. Optionally, start your project with items already added by selecting Import items from repository. All new and existing items from the chosen repository will be added to your project, and it will be designated as your project's default repository.

9. Click Create project.

Creating a user project

1. In the top right corner of GitHub, click your profile picture, then click Your profile.

   

2. On your profile, click Projects.

   

3. Click New project.

4. Select which type of project or template you want to use.

   • To create a blank project, under "Start from scratch", click Table, Roadmap, or Board.
   • To create a project from a template, click the built-in template that you want to use.

5. Optionally, if you selected a template, review the fields, views, workflows, and insights that will be created.

6. In the text box under "Project name", type a name for your new project.

7. Click Create project.

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.

1. Navigate to your project.

2. In the top-right, click to open the menu.

   

3. In the menu, click Settings to access the project settings.

4. To add a short description to your project, under "Add a description", type your description in the text box and click Save.

5. 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 .

6. 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 items to your project

Next, add a few items to your project.

1. Place your cursor in the bottom row of the project, next to the .

   

2. Paste the URL of the issue or pull request.

3. To add the issue or pull request, press Return.

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

For more information and other ways to add issues to your project, or about other items you can add to your project, see Adding items to your project.

Adding draft issues to your project

Next, add a draft issue to your project.

1. Place your cursor in the bottom row of the project, next to the .

   

2. Type your idea, then press Enter.

3. To add body text, click on the title of the draft issue. In the markdown input box that appears, enter the text for the draft issue body, then click Save.

Adding fields

Next, create custom fields to manage the iteration, priority, and estimates for your project items.

Creating an iteration field

Create an iteration field so you can plan and track your work over repeating blocks of time. Iterations can be configured to suit how you and your team works, with customizable lengths and the ability to insert breaks.

1. In table view, in the rightmost field header, click .
   
2. Click New field.
3. At the top of the dropdown, type the name of your new field.
4. Select Iteration
5. To change the duration of each iteration, type a new number, then select the dropdown and click either days or weeks.
6. Click Save.

Specify an iteration for all items in your project.

Creating a priority field