About tasklists

About tasklists

Tasklists add support for hierarchies of issues on GitHub, helping you to keep track of your issues, divide your issues into smaller subtasks, and create new relationships between your issues.

Tasklists build upon the previous iteration of beta task lists, retaining the ability to convert items into issues, display the progress of a tasklist, and create a "tracks/tracked by" relationship between issues.

The issues you add to your tasklists will be automatically populated to show their assignees and any labels applied.

About integration with projects

Your project's side-panel displays an issue's place in the hierarchy on a breadcrumb menu, allowing you to navigate through the issues included in your tasklists. You can also add the Tracks and Tracked by fields to your project views to quickly see the relationships between your issues. For information, see "About Tracks and Tracked by fields."

Creating tasklists with Markdown

You can create a tasklist using Markdown in the issue description (the opening comment of an issue). You can include links to issues and pull requests or create draft issues.

1. Start creating a new issue or edit the issue description of an existing issue.
2. To begin your tasklist, type ```[tasklist] (triple backticks and tasklist inside square brackets) on a new line in the issue description.
3. Optionally, type ### TITLE on the next line, replacing TITLE with a title for your tasklist.
4. For each item you want to add to your tasklist, type - [ ] on a new line, followed by a space, and either a link to an issue, a link to a pull request, or some text to create a draft issue.
   • You must provide a full link to an issue or pull request. For example, https://github.com/octo-org/octo-repo/issues/45.
   • Tasks can be formatted with Markdown.
   • Tasks must not exceed 256 characters in length.
5. To finish your tasklist, type ``` on a new line after the last item.

Your finished tasklist should look like this:

```[tasklist]
### My tasks
- [ ] https://github.com/octo-org/octo-repo/issues/45
- [ ] Draft issue title
```

Your tasklist will be rendered by GitHub when you save the issue. You can then make changes and add issues and draft issues using the GitHub UI. If you edit the issue description, you will be able to modify the Markdown directly or copy the Markdown to duplicate the tasklist in other issues.

You can also click in the formatting toolbar to insert a tasklist when creating a new issue or editing an issue description.

Adding issues to a tasklist

1. At the bottom of your tasklist, click Add item to Tasks.

2. Select the issue to add to your tasklist.

   • To add a recently updated issue from the repository, click the issue in the dropdown, or use your arrow keys to select it and then press Enter.
   • To search for an issue in the repository, start typing the title of an issue or the issue's number and click on the result, or use your arrow keys to select it and press Enter.
   • To add an issue directly using its URL, paste the URL of an issue and press Enter.

Creating draft issues in a tasklist

Draft issues are useful to quickly capture ideas that you can later convert into issues. Unlike issues and pull requests that are referenced from your repositories, draft issues exist only in your tasklist.

1. At the bottom of your tasklist, click Add item to Tasks.
2. In the "Type to add an item or paste in an issue URL" field, type your draft issue title and press Enter.

Converting draft issues to issues in a tasklist

You can convert draft issues into issues. Issues are created in the same repository as the tasklist's parent issue.

1. Next to the draft issue you want to convert, click .

   

2. In the menu, click Convert to issue.

Removing an issue or draft issue from a tasklist

You can remove issues and draft issues from your tasklist. Issues removed from a tasklist are not removed from the repository.

1. Next to the draft issue you want to remove, select .

   

2. In the menu, click Remove.

Changing the title of a tasklist

When you create a new tasklist, the default title is "Tasks." You can modify the title by editing the issue's markdown.

1. In the top-right of the issue body, select and click Edit.

   

2. In the fenced code block that starts with ```[tasklist], add a header with your new title, such as ## My new title.

   

3. Click Update comment.

Copying a tasklist

When you copy your tasklist using the "Copy Markdown" option, GitHub copies Markdown to your clipboard and includes the Issue's name so you can paste the tasklist outside of GitHub without losing context.

1. In the top-right of your tasklist, click .

   

2. In the menu, click Copy markdown.