Connect a Taskboard to a GitHub Repository

Connect a taskboard to a GitHub repository and branch, and the board shows that branch's plan as a roadmap. Each product requirements doc (PRD) becomes a layer, and each prompt brief listed in it becomes a task card. Your team sees what is being built without opening GitHub.

The connection is read-only. Commander never writes to your repository. The branch you connect is the single source of truth: plans are written in the repo, and the board shows them.

Before You Start

You need	Why
To be the owner of the taskboard	Only the board owner can set up or refresh the connection. Other members can view it.
A GitHub repository you can read	Commander reads the branch you choose.
PRDs in docs/01-planning/product-requirements/	That's the only folder the connection reads. Files under a templates/ folder are skipped.

This folder layout comes from the C² Method. If your repo already follows it, there is nothing to change.

Connect the Repository

1. Open the taskboard.
2. Click the Settings button (the vertical three dots, ⋮) at the right of the board's top bar.
3. Open the Connect tab.
4. In Repository, enter the repo as owner/name (for example acme/website).
5. In Branch, enter the branch to follow. It defaults to main.
6. Optional: set a Path scope (see Choose Which PRDs Appear).
7. Click Save Connection.

The banner at the top of the tab changes to Connected to owner/name @ branch.

Authorize Read Access

Once the connection is saved, the Authorize Access section appears. You will see one of two options:

• Connect with GitHub. Click it to install the read-only Waymaker Roadmap GitHub App on the repository, then return to Commander. When it's linked, the tab shows GitHub App installed — pulls run without a token.
• A token field. If the GitHub App isn't available, paste a read-only GitHub token into the field. The token is used for that pull only and is not stored, so you paste it each time you pull.

Pull the Roadmap

1. In the Pull section, click Pull now.
2. Commander reads the branch and shows a summary, for example Pulled 4 PRDs → 4 layers, 12 cards.

The banner shows Last pulled with the date and time.

Pulling is manual. Pushing to GitHub does not update the board on its own. Click Pull now whenever you want the board to catch up with the branch.

Once a board is connected, a Roadmap View button (a map icon) appears in the board's top bar.

How Your Repo Maps to the Board

In the repository	On the taskboard
A PRD file	A layer. The title is the PRD's first # heading, and the PRD's text becomes the layer description.
version, start_date, end_date in the PRD's frontmatter	The layer's version and dates.
area in the PRD's frontmatter	A parent layer that groups PRDs by product area.
Each entry in the PRD's prompt_briefs list	A task card. The title is the brief's first # heading, and the brief's text becomes the card description.
A brief's status	The column the card sits in.

A PRD lists its prompt briefs in its frontmatter:

---
prd: website-relaunch
version: 1.2
area: marketing
prompt_briefs:
  - path: docs/02-working/prompts/active/website/01-homepage.md
    status: done
  - path: docs/02-working/prompts/active/website/02-pricing-page.md
    status: in_progress
---

Status to Column

status in the PRD	Column on the board
backlog (or no status)	Your backlog / to-do column
in_progress	Your in-progress column
review	Your review column
done	Your completed column

Commander matches your board's own columns, even if you've renamed them. If no column matches, the card lands in the first column that isn't a completed column.

To mark work done, change the brief's status in the PRD in your repo, ideally in the same pull request that finishes the work, then pull. Moving a connected card on the board doesn't change your repo.

Choose Which PRDs Appear

By default, the board shows PRDs whose path contains product-requirements/active/, product-requirements/in-progress/ or product-requirements/backlog/. Finished and archived PRDs stay off the roadmap.

To change this, enter a Path scope: a comma-separated list of path fragments. A PRD is included if its path contains any of them. Enter * to include every PRD in the folder.

Your Own Cards Are Safe

A pull only touches cards that came from the repository. Cards your team adds by hand, such as ideas in a layer's backlog column, are never changed or removed.

When an idea graduates into a real prompt brief, add source_card with the card's ID to that brief's entry in the PRD. On the next pull, the existing card is updated in place instead of a duplicate being created:

prompt_briefs:
  - path: docs/02-working/prompts/active/website/03-faq.md
    status: backlog
    source_card: 7f3c2a9e-1b4d-4e8a-9c2f-5d6e7a8b9c0d

Troubleshooting

Message	What to do
Repository must be in "owner/name" format	Enter the repo as owner/name, without https://github.com/.
Connect GitHub or paste a read token to pull	Authorize access first: connect the GitHub App, or paste a read-only token.
Pulled 0 PRDs	Check that your PRDs are in docs/01-planning/product-requirements/ on the connected branch, and that your Path scope matches their folders.
(N warnings) after a pull	Some files couldn't be read. The rest of the roadmap was still updated. Check the PRDs and brief paths named in the repo.
The card didn't move	Change the brief's status in the PRD, commit it to the connected branch, then click Pull now.

Related

• Board Settings & Configuration
• Introduction to Layers
• AI Task Management