## Connect GitHub

1. Open **Settings → Connected sources → GitHub**.
2. Select **Connect GitHub**.
3. Install the Plan Your Work GitHub App on your account or organization.
4. Select the repositories that you want the app to access.
5. GitHub returns you to Plan Your Work to finish connecting.
6. Authorize access with your GitHub account.

If your organization already installed the app, select **Connect with existing access** to skip installation.
Use **Choose repositories on GitHub** to add repository access for a connected account.

Your organization may require an owner to approve installation or repository access.
If the connect button is disabled, the server administrator must configure the GitHub App first.

Select **Add GitHub account** to connect another account.
Each connection represents a GitHub login, with its own preferences, imported lists, and credentials.
Open **Connect another login with existing app access** to use another login without installing again.
Installing the app in another organization expands access for that login; it does not create a second account card.
**Repository access** lists available personal and organization installations, their repository selection, and any suspension.
Select **Add organization** to install the app for another organization.
Repository lists appear only when matching tasks are found. Empty repositories do not create lists.
Reconnect with the same GitHub account to renew an existing connection.

## Choose assignments and reviews

Each connection can import:

- Open issues assigned to you.
- Open pull requests assigned to you.
- Open pull requests you opened.
- Pull requests with a review request for you.
- Pull requests with a review request for a team you belong to.

All five categories are enabled initially.
In the connection settings, select the assignment categories and teams you want, then select **Save preferences**.
Team reviews can remain enabled when personal review requests are disabled.

Within a connection, a pull request appears once, even when you and several teams must review it.
The issue or PR number appears beside its source icon.
Hover over that number to see why the item was imported.
Use **Links** to open the original item in GitHub.

## See where a pull request stands

Each open pull request shows its review state beside its number, and how long it has been in that state:

| State | Meaning | Time counts from |
| --- | --- | --- |
| Draft | The pull request is a draft. | Opened, or converted back to draft |
| Review requested | Someone else's pull request waits on a review from you or your team. | Marked ready, or the last review if it went back for another round |
| Waiting on review | Your pull request has a review request for a person or team. | Marked ready, or the last review if it went back for another round |
| No reviewer | Your pull request is ready, but nobody has a review request or has reviewed it. | Marked ready, or opened if it was never a draft |
| Changes requested | A reviewer's latest decision requests changes. | That review |
| Approved | Reviewers approved, and nobody's latest decision requests changes. | The first current approval |
| Reviewed | Reviewers commented without approving or requesting changes. | The last review |

The time turns amber after one day.
In an area with working hours, the time counts only working time, and a day means one working day.
The Work area starts with Monday to Friday, 9 to 5. Change it, or set hours for other areas, in **Settings → Working hours**.
A pull request that waits on you, in **Review requested**, **Changes requested**, or **Approved**, appears in **Today** once it has waited one day.
Set **Show from** to put it off until later. Dependency updates stay out of Today.
To see one state, such as **Approved**, choose it from the state filter on **All tasks** or a list.
The same filter lists Shortcut workflow states when Shortcut stories are in view.

To see every state at once, sort **All tasks**, a list, or a folder by **State**. Lists and folders offer the sort when their tasks have states. Each state gets its own section, with the states that need you first:
Review requested, Changes requested, Approved, No reviewer, Reviewed, Waiting on review, then Draft.
Shortcut workflow states follow in their workflow order, then tasks without a state.
Within each section, the pull request that has waited longest comes first.
Select a section's title to collapse or expand it. Plan Your Work remembers your choice in this browser.

A pull request that names a Shortcut story, such as `sc-5807` in its title, branch, or description, shows that story and its workflow state.
The story shows the pull request and its review state in return. Select either one to open the other.
A story that is not in Plan Your Work still shows its number, linked to Shortcut when you connect only one Shortcut workspace.

With **Dependency updates** on, Plan Your Work imports Dependabot and Renovate pull requests opened in the last 90 days, in every account the app is installed on, even when nobody is assigned.
Dependabot pauses a repository whose pull requests sit untouched for 90 days, so older ones drop out. They stay only if they are assigned to you or request your review.
Pull requests from Dependabot and Renovate appear after your other tasks.
In a view with sections, they move to a **Dependency updates** section at the end, collapsed until you expand it.
Turn off **Dependency updates** in the connection settings to leave them out entirely.
Reviews and review requests from bots, such as Copilot, do not count. Your own replies to your pull request do not count either.
States refresh with each sync.

Authored issues, mentions, notifications, and discussion participation alone do not cause an import.
A new connection imports open work, not the full history of closed issues and pull requests.

## Organize repositories

Each account or organization gets a folder with its name and the GitHub icon. Each repository becomes a list in its owner's folder, named for the repository alone:

```text
ten-thousand-hammers
  mend
  nategent
uptick-ads
  platform
  ios-sdk
```

You can rename an owner folder or move it into another folder. New repositories from that owner still go into it. If you archive an owner folder, the next new repository from that owner gets a new folder at the top level, with the archived folder's name.
With [areas](projects.md#separate-your-areas) enabled, new owner folders start in **Work**, unless you select another area in the connection settings. Repository lists take their folder's area.
Existing lists keep their names, areas, and parent projects after sync.
Lists imported before owner folders were added are renamed and moved into their owner's folder once, on the first sync.

You can rename a repository list or link it to an existing project.
Linking brings tasks together in Plan Your Work. It does not copy tasks between external sources.
You can also move an imported task to another local list. Its GitHub repository stays the same.

## What syncs back

You can edit imported items that you authored or are assigned to.
For review-only items, including team reviews, you can set **Due date** and **Show from** in the task editor.
These dates stay in Plan Your Work and survive GitHub sync. Title, notes, and priority remain protected.
You can complete review-only pull requests in Plan Your Work, as described in [Complete review tasks](#complete-review-tasks).
You can still open their links, move them between local lists, and reorder them.
The same rule applies to edit controls, keyboard commands, and MCP agents.
Ownership is refreshed during sync and checked again before each GitHub update.

The following edit options apply to items you authored or are assigned to:

| Change in Plan Your Work | GitHub issue | GitHub pull request |
| --- | --- | --- |
| Edit title | Syncs | Syncs |
| Edit notes | Updates the issue body | Updates the PR body |
| Complete | Closes the issue as completed | Managed in GitHub |
| Reopen | Reopens the issue | Managed in GitHub |
| Set due date, priority, or Show from | Stays local | Stays local |
| Move to another list | Stays local | Stays local |
| Create a task | Stays local | Stays local |
| Delete an imported item | Delete in GitHub | Delete in GitHub |

Notes edit the body, not a comment.
GitHub applies your account and app permissions to each update.
If an update fails, the connection shows an error and retains the pending change for retry.

A draft pull request that you authored or are assigned to shows **Mark ready**. Select it to mark the draft ready for review in GitHub.
This needs a connection; the task shows its new state when GitHub confirms the change.

Merge or close pull requests and submit reviews in GitHub.
Pull requests that you authored or are assigned to show a PR marker instead of a completion checkbox.
GitHub items cannot use automatic task completion.

These limits also apply to [AI agents connected through MCP](mcp.md).
Task results include source metadata, editable fields, and whether completion is managed by the source.
Agents can read this guide with `get_documentation` using `slug: "github"`.

## Complete review tasks

A review-only pull request shows the usual completion checkbox, its PR number, and its **Links** to GitHub.
Select the checkbox, press Space on the selected task, or use the command palette to complete it.
Completing a review task here does not submit a review, approve, close, or merge the pull request in GitHub.
The task stays complete after later syncs, even while the review request remains.
Reopen it to return it to your list. A later sync can complete it again if a qualifying approval exists.

Review tasks also complete automatically when sync finds a qualifying approval in GitHub:

- A personal review task completes when you approve the pull request.
- A team review task completes when you or anyone else approves the pull request.
- When one task has both a personal and a team review request, the team rule applies, so another person's approval completes it.

Comments, requested changes, and draft reviews do not complete a task.
Each reviewer's latest approval, change request, or dismissal counts as that reviewer's current decision.
If a reviewer requests changes after approving, their earlier approval no longer counts.
A completed review task stays complete if a reviewer requests changes later.

Approval never completes a pull request that you authored or are assigned to, even when it also has review requests.
Those tasks still complete when the pull request closes or merges.

Approvals appear after the next sync, which runs every five minutes.
Select **Sync now** to check sooner.
If GitHub no longer lists your review request, the task stays until you approve or complete it, while that review category or team remains selected.

## Refresh and remove work

Plan Your Work checks connected accounts every five minutes.
Select **Sync now** to request an earlier refresh.
Supported local edits also queue a sync automatically.

When an imported issue closes or a pull request closes or merges, it completes locally after sync.
When an open item no longer matches any selected assignment or review category, it leaves the local list after sync.
Unfinished review tasks are the exception described in [Complete review tasks](#complete-review-tasks).
Pending edits are preserved until they can sync.
GitHub search can take time to reflect new assignments and review requests.

Select **Disconnect** to remove that connection’s imported tasks and stored credentials from Plan Your Work.
Local tasks and tasks from other connections remain. GitHub issues and pull requests remain unchanged.
To revoke the app’s GitHub access too, use your GitHub application settings.

## Troubleshoot access

If a repository or team is missing, check the app installation and organization approval in GitHub.
The app needs access to the repository and organization members to discover team reviews.
Your GitHub account must also have access.

If authorization expires or permissions change, select **Reconnect**, then **Sync now**.
If GitHub limits requests, sync retries after the limit resets.
An incomplete or failed search does not remove existing tasks.
Connections with more than 1,000 results in one search must reduce repository access or narrow the enabled categories.