Skip to main content

Quickstart for Projects

Experience the speed, flexibility, and customization of Projects by creating a project in this interactive guide.

Introduction

This guide demonstrates how to use Projects 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

  1. In the top right corner of GitHub.com, click your profile photo, then click Your organizations. Your organizations in the profile menu

  2. Click the name of your organization. Organization name in list of organizations

  3. Under your organization name, click Projects. Screenshot showing the 'Projects' tab

  4. Click New project. Screenshot showing New project button

  5. When prompted to select a template, click a template or, to start with an empty project, click Table or Board. Then, click Create.

    Screenshot showing template selection modal

Creating a user project

  1. In the top right corner of GitHub.com, click your profile photo, then click Your profile. Profile photo

  2. On your profile, click Projects. Screenshot showing the 'Projects' tab

  3. Click New project. New project

  4. When prompted to select a template, click a template or, to start with an empty project, click Table or Board. Then, click Create.

    Screenshot showing template selection modal

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. Screenshot showing the menu icon
  3. In the menu, click Settings to access the project settings. Screenshot showing the 'Settings' menu item
  4. To add a short description to your project, under "Add a description", type your description in the text box and click Save. Screenshot showing the 'Add my description' settings
  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 . Screenshot showing editing a project's README
  6. To save changes to your README, click Save. Screenshot showing the 'Save' button for a project's README

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.

  1. Place your cursor in the bottom row of the project, next to the . Screenshot showing the bottom row to add an item
  2. Paste the URL of the issue or pull request. Screenshot showing pasting an issue URL to add it to the project
  3. To add the issue or pull request, press Return.

Repeat the above steps a few times to add multiple issues 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 . Screenshot showing the bottom row to add an item
  2. Type your idea, then press Enter. Screenshot showing pasting an issue URL to add it to the project
  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 an iteration field

Next, 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 . Screenshot showing new field button
  2. Click New field. Screenshot showing new field menu item
  3. Type the name of your new field. Screenshot showing the field name
  4. Select Iteration Screenshot showing the iteration option
  5. To change the duration of each iteration, type a new number, then select the dropdown and click either days or weeks. Screenshot showing the iteration duration
  6. Click Save. Screenshot showing save button

Creating a field to track priority

Now, create a custom field named Priority and containing the values: High, Medium, or Low.

  1. In table view, in the rightmost field header, click . Screenshot showing new field button
  2. Click New field. Screenshot showing new field menu item
  3. Type the name of your new field. Screenshot showing the field name
  4. Select Single select Screenshot showing the single select option
  5. Below "Options", type the first option, "High". Screenshot showing the single select option
  6. To add additional fields, for "Medium" and "Low", click Add option.
  7. Click Save. Screenshot showing save button

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.

  1. Click next to the name of the currently open view. Screenshot showing the view menu icon
  2. Click Group. Screenshot showing the group menu item
  3. Click Priority. Screenshot showing the group menu

Now, move issues between groups to change their priority.

  1. Choose an issue.
  2. 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.

  1. Click next to the name of the currently open view. Screenshot showing the view menu icon
  2. Click Save changes. Screenshot showing the save menu item

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.

  1. To the right of your existing views, click New view Screenshot showing the column field menu

Next, switch to board layout.

  1. Click next to the name of the currently open view. Screenshot showing the view menu icon
  2. Under "Layout", click Board. Screenshot showing layout option

Example priorities

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.

  1. Click next to the name of the currently open view. Screenshot showing the view menu icon
  2. Click Save changes. Screenshot showing the save menu item

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

  1. Click next to the name of the currently open view. Screenshot showing the view menu icon
  2. Click Rename view. Screenshot showing the rename menu item
  3. Type the new name for your view.
  4. To save changes, press Return.

Example priorities

Configure built-in automation

Finally, add a built in workflow to set the status to Todo when an item is added to your project.

  1. In the top-right, click to open the menu. Screenshot showing the menu icon
  2. In the menu, click Workflows. Screenshot showing the 'Workflows' menu item
  3. Under Default workflows, click Item added to project. Screenshot showing default workflows
  4. Next to When, ensure that both issues and pull requests are selected. Screenshot showing the "when" configuration for a workflow
  5. Next to Set, select Status:Todo. Screenshot showing the "set" configuration for a workflow
  6. Click the Disabled toggle to enable the workflow. Screenshot showing the "enable" control for a workflow

Further reading