GitHub Projects in VS Code
Work with GitHub Projects (v2) without leaving the editor: the same board, table and roadmap
views you see at github.com/users/<owner>/projects/<n>, with cards you can move.
Features
- Projects tree in the Activity Bar: your user, your organizations, the owners of projects
shared with you (linked to repositories you collaborate on) and any owner you add, with their
open projects and views.
- Each view shows what it shows on GitHub: the view's own filter (
-status:Done,
assignee:@me, sprint:@current…) is applied by GitHub itself, and can be switched off.
- Board grouped by the view's "Column by" field (or
Status, or the first single-select
field), with swimlanes when the view has a "Group by" field (or pick one in the toolbar). Cards show number, title, repository, labels, assignees and custom fields
(single-select, iteration, number, date, text). Works with projects of any size: items are
loaded 100 at a time.
- Table views with the fields the view shows on GitHub, in the same order, plus its sort and
group-by. Click a column header to sort, pick a field to group by, click a cell to edit it, and
drag rows to another group or position.
- Roadmap views: items as bars on a timeline with month headers, iterations and a line for
today. Bars use an iteration field or date fields (start and target), colored by Status, with
Month / Quarter / Year zoom. Drag a bar, or its ends, to change its dates.
- Move cards by drag & drop, with the Move menu or with Alt+←/→,
and reorder them inside a column (Alt+↑/↓). Changes show at once;
if GitHub rejects one it goes back and you get a warning.
- Add items: "+ Add item" at the bottom of a column or table group creates a draft issue with
that column's or group's value.
- Filters and search: text search (
#123, repository, labels…) plus label, assignee and any
single-select field. Filters are remembered per project and workspace.
- Item details: the issue or pull request body, its project fields (editable), labels and
assignees, with Open on GitHub, Copy link and, if the
GitHub Pull Requests
extension is installed, Open in GitHub Pull Requests.
- Refresh on demand, optional polling and a status bar counter of the items assigned to you
that are "In progress".
- Follows your VS Code theme (light, dark and high contrast).
Installation
Install GitHub Projects in VS Code from the
Visual Studio Marketplace:
In VS Code, open the Extensions view (Ctrl/Cmd+Shift+X),
search for GitHub Projects in VS Code and choose Install, or
from a terminal:
code --install-extension guilletin63.vscode-gh-projects
Requires VS Code 1.99 or later. Each version is also attached to the
GitHub releases as a .vsix file
(Extensions view → … → Install from VSIX…), and you can build it yourself with
npm ci && npm run package.
How to use
1. Sign in
Open the GitHub Projects view in the Activity Bar and choose Sign in to GitHub. The
extension uses the GitHub account VS Code already knows; nothing to configure.
2. Open a board
Your user and organizations are listed with their open projects, followed by people or
organizations whose projects are linked to repositories you collaborate on (shared with
you). Click a project to open its board, or expand it and pick one of its views. Use Add
Owner… (＋ in the view title) for an owner that doesn't show up on its own.
3. Table and roadmap views
Each view opens with its own layout: boards as columns, tables as rows with the view's fields,
and roadmaps as a timeline. Switch views with the View menu in the panel or from the tree.
GitHub doesn't share which date fields a roadmap view uses, so pick them with Start and
Target (an iteration field, a date field or one of each). The first time, the extension uses
the project's iteration field, or date fields named like Start and Target / Due. Items
without dates are listed at the end. Click a row or a bar to open its details.
Editing works in every layout:
|
Board |
Table |
Roadmap |
| Change a field |
drag to a column |
drag to a group, or click a cell |
drag a bar or its ends (date fields) |
| Keyboard |
Alt+←/→ |
Alt+↑/↓ across groups |
Alt+←/→ (+Shift: target only) |
| Reorder |
drag inside a column, Alt+↑/↓ |
drag, Alt+↑/↓ (unsorted tables) |
— |
| New draft |
+ Add item |
+ Add item |
— |
Views keep the filter saved with them on GitHub: a line under the search box shows it, with
Show all items to see the whole project. Boards with a "Group by" field show swimlanes; drop
a card in another lane to change that field too.
4. Move cards
Drag a card to another column. It moves immediately and GitHub is updated in the background; if
the update fails, the card goes back and you get a warning. Without a mouse: focus a card and use
the Move menu or Alt+←/→. The status bar counter
("1 in progress") follows your own items.
5. Filter and search
Type in the search box (#123, words from titles, repository, labels…) or pick values in the
Label, Assignee and field menus. Values inside a menu are combined with OR, menus with
AND. Filters are remembered per project.
6. Item details
Click a card (or a table row, or a roadmap bar) to read its description and edit its project fields. Open on GitHub and
Copy link are one click away.
Light theme
Permissions and privacy
- Sign-in goes through VS Code's built-in GitHub authentication. Reading asks for the
read:project, read:org (to list your organizations) and repo scopes. The first time you
move a card or edit a field, VS Code asks for the project scope.
- The extension keeps nothing of your GitHub session: VS Code holds the sign-in, and nothing is
written to settings, disk or logs.
- No usage data is collected. The extension only talks to
api.github.com.
- The board runs in a webview with a strict Content Security Policy and no remote scripts.
Settings
| Setting |
Default |
Description |
ghProjects.refreshInterval |
0 |
Seconds between automatic refreshes of visible boards and the counter. 0 disables polling; the minimum is 30. Polling pauses while the window is not focused and slows down when GitHub rate-limits. |
ghProjects.inProgressColumn |
In progress |
Column counted in the status bar for items assigned to you (case-insensitive). |
Commands
- GitHub Projects: Sign in to GitHub
- GitHub Projects: Refresh (tree and open boards)
- GitHub Projects: Add Owner…
- GitHub Projects: Open Last Board
Known limitations
- Tables don't show the Reviewers and Tracks / Tracked by fields; the table says which fields it
leaves out. Built-in fields (assignees, labels…) are edited on GitHub.
- Sorted views have no manual order, like on github.com: reordering is off while a sort applies.
- Roadmap bars that use an iteration field can't be dragged; change the iteration from the
table or the item details.
- A roadmap's date fields, zoom and markers set on github.com aren't available through GitHub's
API; choose the dates in the panel (remembered per view).
- Organizations whose membership is private, and projects shared with you that aren't linked to
any repository you collaborate on, may not be listed automatically; add their owner with
Add Owner….
Contributing
See CONTRIBUTING.md for the architecture, commands and tests.
License
MIT. Drag & drop uses SortableJS (MIT).
| |
