Skip to main content

Creating a project (beta)

Learn how to make a project, populate it, and add custom fields.

Projects are a customizable collection of items that stay up-to-date with GitHub data. Your projects can track issues, pull requests, and ideas that you jot down. You can add custom fields and create views for specific purposes.

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

Creating a project

Creating an organization project

  1. On GitHub, navigate to the main page of your organization.

  2. Click Projects.

  3. Select the New project drop-down menu and click New project (Beta).

    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

Creating a user project

  1. On any GitHub page, click on your avatar, then select Your projects.

  2. Select the New project drop-down menu and click New project (Beta).

    New project

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

Updating 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

Your project can track draft issues, issues, and pull requests.

Creating draft issues

Draft issues are useful to quickly capture ideas.

  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.

Draft issues can have a title, text body, assignees, and any custom fields from your project. In order to populate the repository, labels, or milestones for a draft issue, you must first convert the draft issue to an issue. For more information, see "Converting draft issues to issues."

Note: Users will not receive notifications when they are assigned to or mentioned in a draft issue unless the draft issue is converted to an issue.

Issues and pull requests

Paste the URL of an issue or pull request

  1. Place your cursor in the bottom row of the project, next to the .
  2. Paste the URL of the issue or pull request.

Searching for an issue or pull request

  1. Place your cursor in the bottom row of the project, next to the .
  2. Enter #.
  3. Select the repository where the pull request or issue is located. You can type part of the repository name to narrow down your options.
  4. Select the issue or pull request. You can type part of the title to narrow down your options.

Adding multiple issues or pull requests from a repository

  1. On GitHub.com, navigate to the repository that contains the issues or pull requests you want to add to your project.
  2. Under your repository name, click Issues or Pull requests. Issues and pull requests tab selection
  3. To the left of each issue title, select the issues that you want to add to your project. Screenshot showing checkbox to select issue or pull request
  4. Optionally, to select every issue or pull request on the page, at the top of the list of issues or pull requests, select all. Screenshot showing checkbox to select all on screen
  5. Above the list of issues or pull requests, click Projects (beta). Screenshot showing checkbox to select all on screen
  6. Click the projects you want to add the selected issues or pull requests to. Screenshot showing checkbox to select all on screen

Assigning a project from within an issue or pull request

  1. Navigate to the issue or pull request that you want to add to a project.

  2. In the side bar, click Projects.

  3. Select the project that you want to add the issue or pull request to.

  4. Optionally, populate the custom fields.

    Project sidebar

Converting draft issues to issues

In table layout:

  1. Click the on the draft issue that you want to convert.
  2. Select Convert to issue.
  3. Select the repository that you want to add the issue to.
  4. Alternatively, edit the labels, milestone, or repository fields of the draft issue that you want to convert.

In board layout:

  1. Click the on the draft issue that you want to convert.
  2. Select Convert to issue.
  3. Select the repository that you want to add the issue to.

Removing items from your project

You can archive an item to keep the context about the item in the project but remove it from the project views. You can delete an item to remove it from the project entirely.

  1. Select the item(s) to archive or delete. To select multiple items, do one of the following:
    • Command+Click (Mac) or Ctrl+Click (Windows/Linux) each item.
    • Select an item then Shift+ or Shift+ to select additional items above or below the initially selected item.
    • Select an item then Shift+Click another item to select all items between the two items.
    • Enter Command+A (Mac) or Ctrl+A (Windows/Linux) to select all items in a column in a board layout or all items in a table layout.
  2. To archive all selected items, enter E. To delete all selected items, enter Del. Alternatively, select the (in table layout) or the (in board layout), then select the desired action.

You can restore archived items but not deleted items. For more information, see Restoring archived items.

Restoring archived items

  1. Navigate to your project.

  2. In the top-right, click .

  3. In the menu, click Archived items.

  4. Optionally, to filter the archived items displayed, type your filter into the text box above the list of items. For more information about the available filters, see "Filtering projects (beta)."

    Screenshot showing field for filtering archived items

  5. To the left of each item title, select the items you would like to restore.

    Screenshot showing checkboxes next to archived items

  6. To restore the selected items, above the list of items, click Restore.

    Screenshot showing the "Restore" button

Adding fields

As field values change, they are automatically synced so that your project and the items that it tracks are up-to-date.

Showing existing fields

Your project tracks up-to-date information about issues and pull requests, including any changes to the title, assignees, labels, milestones, repository, reviewers, and linked pull requests. When your project initializes, "title" and "assignees" are displayed; the other fields are hidden. You can change the visibility of these fields in your project.

  1. To open the project command palette, press Command+K (Mac) or Ctrl+K (Windows/Linux).
  2. Start typing "show".
  3. Select the desired command (for example: "Show: Repository").

Alternatively, you can do this in the UI:

  1. Click in the rightmost field header. A drop-down menu with the project fields will appear. Show or hide fields
  2. Select the field(s) that you want to display or hide. A indicates which fields are displayed.

Adding custom fields

You can add custom fields to your project. Custom fields will display on the side bar of issues and pull requests in the project.

Custom fields can be text, number, date, single select, or iteration:

  • Text: The value can be any text.
  • Number: The value must be a number.
  • Date: The value must be a date.
  • Single select: The value must be selected from a set of specified values.
  • Iteration: The value must be selected from a set of date ranges (iterations). Iterations in the past are automatically marked as "completed", and the iteration covering the current date range is marked as "current". For more information, see "Managing iterations in projects."
  1. To open the project command palette, press Command+K (Mac) or Ctrl+K (Windows/Linux). Start typing any part of "Create new field". When "Create new field" displays in the command palette, select it.
  2. Alternatively, click in the rightmost field header. A drop-down menu with the project fields will appear. Click New field.
  3. A popup will appear for you to enter information about the new field. New field
  4. In the text box, enter a name for the new field.
  5. Select the dropdown menu and click the desired type.
  6. If you specified Single select as the type, enter the options.
  7. If you specified Iteration as the type, enter the start date of the first iteration and the duration of the iteration. Three iterations are automatically created, and you can add additional iterations on the project's settings page.

You can also edit your custom fields.

  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. Under Fields, select the field that you want to edit.

  5. For single select fields, you can add, delete, or reorder the options.

  6. For iteration fields, you can add or delete iterations, change iteration names, and change the start date and duration of the iteration.

    For more information on modifying iteration fields, see "Managing iterations in projects."

Customizing your views

You can view your project as a table or board, group items by field, filter item, and more. For more information, see "Customizing your project (beta) views."

Configuring built-in automation

Projects (beta) includes built-in workflows that you can use to update the Status of items based on certain events. For example, you can automatically set the status to Todo when an item is added to your project or set the status to Done when an issue is closed.

When your project initializes, two workflows are enabled by default: When issues or pull requests in your project are closed, their status is set to Done, and when pull requests in your project are merged, their status is set to Done.

You can enable or disable the built-in workflows for your project.

  1. Navigate to your project.
  2. In the top-right, click to open the menu.
  3. In the menu, click Workflows.
  4. Under Default workflows, click on the workflow that you want to edit.
  5. If the workflow can apply to both issues and pull requests, next to When, check the item type(s) that you want to act on.
  6. Next to Set, choose the value that you want to set the status to.
  7. If the workflow is disabled, click the toggle next to Disabled to enable the workflow.

Adding your project to a repository

You can list relevant projects in a repository. You can only list projects that are owned by the same user or organization that owns the repository.

In order for repository members to see a project listed in a repository, they must have visibility for the project. For more information, see "Managing the visibility of your projects (beta)" and "Managing access to projects (beta)."

  1. On GitHub, navigate to the main page of your repository.
  2. Click Projects.
  3. Click Projects (Beta) in the side bar.
  4. Click Add project.
  5. In the search bar that appears, search for projects that are owned by the same user or organization that owns the repository.
  6. Click on a project to list it in your repository.