GitHub Integration

Setup

Connect Canopy to GitHub by adding a personal access token in Settings > GitHub. The token needs repo scope for private repositories, or public_repo for public-only access.

After entering your token, click Validate to verify it works. The token is stored in your OS keychain via Electron's safeStorage API.

Repo Stats

When a GitHub token is configured, the toolbar's GitHub Stats button shows live counts of:

• Open issues assigned to the repository
• Open pull requests
• Unpushed commits on the current branch

These update automatically. Clicking any of the counts opens the corresponding dropdown panel. If the toolbar is narrow, the GitHub stats may appear in the ··· overflow menu instead.

Issues and PR Panel

Click the issue or PR count in the toolbar to open the dropdown panel. The panel opens with the search input focused, so you can start typing immediately to find what you need.

At the top of the panel, state filter tabs let you narrow the list. Issues show Open and Closed tabs. PRs show Open, Merged, and Closed.

The panel also supports number-based search patterns for quick lookups:

• #42 fetches a single issue or PR by number
• 42,45 fetches multiple specific items
• 42-50 fetches a range
• 42+ fetches an open-ended range from that number onwards

At the bottom of the panel, View on GitHub opens the filtered list on GitHub.com, and New opens GitHub to create a new issue or PR.

Keyboard Navigation

You can navigate the panel entirely from the keyboard:

• ↑ / ↓ moves through the list from the search input
• Enter creates a worktree for the focused item (if open and no worktree exists) or switches to it (if a worktree already exists)
• Cmd+Enter (or Ctrl+Enter) opens the focused item on GitHub
• Escape clears the current selection first, then closes the panel on a second press

Sort Order

A filter icon next to the search input opens a sort popover with two options:

• Recently updated (default): sorts by last activity
• Newest: sorts by creation date

When a non-default sort is active, a small accent dot appears on the filter icon so you can tell at a glance. The sort preference is tracked separately for issues and PRs.

Row Details

Each row in the panel shows a two-line layout with the key information at a glance:

• Top row: state icon, title, CI status indicator (open PRs only), and the #number badge (click it to copy the number to your clipboard)
• Bottom row: author, time since last update, branch name (PRs) or labels (issues, up to two shown with color dots), comment count, linked PR icon (issues with an associated PR), assignee avatar, worktree indicator, and a ··· context menu

The ··· context menu on each row offers Open in GitHub, Switch to Worktree (if one exists), and Create Worktree (if the item is open and no worktree exists). Fork PRs show the create option as disabled with a tooltip explaining the limitation.

CI Status Icons

Open PR rows display a CI status indicator between the title and the PR number:

• Green check: all checks passed
• Amber dot: checks pending
• Red X: checks failing

Hover over the icon for a tooltip describing the status. If no CI checks are configured for the PR, no indicator appears.

Instant Loading

The first time you open the panel, it shows a skeleton loader while fetching from GitHub. After that initial load, re-opening the panel displays the cached data instantly while a background refresh happens silently. You get to see your issues and PRs right away without waiting for the network.

The cache is keyed by project, resource type, filter state, and sort order, so switching any of those triggers a fresh fetch. Search results always fetch live and are not cached.

Creating Worktrees from Issues

The quickest way to start on a GitHub issue is to create a worktree directly from it:

1. Click the issues count in the toolbar to open the issues panel
2. Find or search for the issue you want to work on
3. Click Create Worktree on the issue row
4. The create worktree dialog opens with the issue pre-linked

What Gets Auto-Populated

When you create a worktree from an issue, Canopy automatically fills in:

• Branch name: generated from the issue title and number (e.g., feature/issue-42-add-dark-mode). The branch prefix is inferred from issue labels and title keywords (bugfix/ for bugs, docs/ for documentation, etc.).
• Worktree path: auto-populated based on your configured path pattern
• Base branch: defaults to main or master

You can edit all fields before creating. If a branch name already exists, Canopy auto-increments it (e.g., feature/issue-42-add-dark-mode-1).

Assign to Self

When your GitHub user is authenticated, the dialog shows an Assign to me toggle. Enabling this assigns the issue to you on GitHub when the worktree is created. This preference is remembered across sessions.

Run Recipe on Create

If you have recipes configured, you can pick one to auto-run when the worktree is created, launching your preferred agents and terminals right away.

Creating a Worktree from a PR

You can also create a worktree directly from a pull request. Each open PR row in the dropdown panel has a Create Worktree action (visible on hover or via the ··· menu).

The create dialog opens in a checkout mode tailored for PRs. It shows a PR info banner and pre-fills the branch name from the PR's head branch. If the remote branch has been fetched locally, Canopy uses it as the checkout target. When the branch hasn't been fetched yet, Canopy shows a warning and disables the create button to prevent accidentally branching off main instead.

Bulk Worktree Creation

When you need to set up worktrees for several issues or PRs at once, the bulk creation flow saves you from doing them one at a time.

Selecting Items

Hover over the state icon on any row and it turns into a checkbox. Click to select that item. Once one item is selected, all rows switch to showing checkboxes, making it easy to continue selecting.

Use Shift+click to select a range between the last selected item and the one you click. Escape clears the selection on the first press, then closes the panel on the second.

When a search is active, Select all and Select unassigned (issues only) shortcut buttons appear in the panel header for quick bulk selection.

Bulk Action Bar

As soon as you select one or more items, a floating bar slides up from the bottom of the panel. It shows the number of selected items, a Create Worktrees button, and an X to clear the selection.

Reviewing Before Creating

Clicking Create Worktrees opens a dialog showing every selected item with its planned branch name. Items that can't be created are shown dimmed with a badge explaining why:

• Closed or Merged: the issue or PR is no longer open
• Has worktree: a worktree already exists for this item
• No branch info: the PR is missing a head branch reference

The dialog also includes an Assign to me toggle (issues only) and an optional recipe picker if you want to launch agents immediately in each new worktree.

Creation Progress

Once you confirm, Canopy creates the worktrees two at a time. Each item shows its own progress indicator: a spinner while in progress, a checkmark when done, or a warning icon if something went wrong. A progress bar and summary line track the overall count.

Transient errors (git lock files, rate limits, connection issues) are automatically retried up to twice with backoff. This handles most of the common hiccups without any intervention.

When Creation Finishes

Once the batch completes, the dialog shows a summary. If any items failed, a Retry Failed button re-queues only the failed items (already-created worktrees are left as-is). Clicking Done closes the dialog and switches to the last successfully created worktree.

A system notification also confirms the result, showing how many worktrees were created.

Automatic Issue Detection

Canopy parses branch names to detect linked GitHub issues. Recognized patterns include:

• feature/issue-42-fix-header
• bugfix/gh-15-login-bug
• issues/123

When an issue is detected:

• The worktree card shows an issue badge with the issue number and title
• Issue state (open/closed) is tracked

Manual Issue Linking

If a worktree already exists and you want to link it to a GitHub issue after the fact, you can attach one manually. This is useful when you've started work before an issue was filed, or when automatic detection from the branch name doesn't match the right issue.

1. Right-click a worktree card, or click the ... button in the card header to open the context menu
2. Select Attach to Issue… (or Change Issue… if an issue is already linked)
3. The Attach Issue dialog opens with a search field and filter tabs
4. Search by title or issue number, and use the Open, Closed, or All tabs to filter by state
5. Select an issue from the list to attach it

The Attach Issue Dialog

The dialog provides a searchable, filterable list of issues from the repository. A few things to note:

• The search field filters by both title and issue number, with a short debounce so results update as you type
• State filter tabs (Open, Closed, All) let you attach closed issues too. The filter resets to Open each time the dialog opens
• Keyboard navigation works with ↑ and ↓ to move through the list, and Enter to attach the selected issue
• If an issue is already attached to the worktree, it appears in the list with an attached badge so you can see the current link at a glance

Detaching an Issue

To remove a linked issue, open the same dialog (via Change Issue… in the menu). A Detach Issue button appears in the dialog footer when an issue is currently attached. Clicking it removes the association entirely.

Effect on the Worktree Card

When any issue is linked to a worktree (whether manually attached or automatically detected from the branch name), the worktree card updates to reflect the link:

• The issue title becomes the card's primary headline, replacing the branch name at the top
• The branch name moves to a secondary row below the headline
• Clicking the issue title opens the issue on GitHub in your browser
• Hovering over the issue title shows a tooltip with full issue details (title, description, labels, and state)

Persistence

Issue associations are stored in Canopy's local settings, not in your git repository. They survive app restarts and are cleaned up automatically when you delete the worktree. Each worktree can have one attached issue at a time.

Automatic PR Detection

When you switch to a worktree, Canopy checks if the branch has an open pull request on GitHub. If one exists:

• The worktree card shows a PR badge with the PR number and state (open, draft, merged, or closed). When a remote is connected but no PR exists, the badge reads "No PR".
• PR status is polled periodically to keep the badge current
• Click the badge to open the PR in the Portal

Hover Tooltips

Hover over a PR or issue badge on a worktree card to see more details: title, description summary, labels, and current state, pulled directly from the GitHub API.

Per-Project GitHub Remote

The token you add in Settings > GitHub applies globally. The remote selection below is a separate, per-project setting.

By default, Canopy uses the origin remote to connect to GitHub. If your project has multiple remotes (common when working with forks), you can choose which one Canopy uses for issues, PRs, and pulse data.

Open Project Settings and go to the GitHub tab. A dropdown lists all configured git remotes, each showing its name and owner/repo label. Pick the remote that points to the repository you want Canopy to integrate with.

The default option, Auto-detect (origin), preserves the standard behavior. You only need to change this if your origin remote points to a fork and you'd rather track issues and PRs on the upstream repository.