Cards that follow GitHub

Connect a venture to its GitHub repository and its cards move by themselves:

• Someone starts work on a feature's branch (pushes to it, or opens a pull request): the card moves to In Progress.
• That branch is merged into your main branch: the card moves to Shipped.

It doesn't matter who builds it or with which tool: Claude Code, the flowmaps command, Cursor, or a freelancer.

How Flowmaps knows which card

By the branch name. Every feature gets one, like flowmaps/v0.2.0-customers-can-book-a-walk. Claude Code and the flowmaps command use it by themselves. Working with someone else? Give them the branch name from the card's build instructions.

Branches with other names are ignored, so normal work on your project doesn't move anything.

Connect (once per venture)

1. Open the venture and click Connect GitHub at the top.
2. Paste the repository's address, like github.com/you/your-app, and click Connect.
3. Flowmaps shows a Payload URL and a Secret. Click the link to your repository's Settings → Webhooks → Add webhook and fill in:
   • Payload URL: paste it.
   • Content type: application/json.
   • Secret: paste it. You only see it once.
   • Which events? Let me select individual events, then tick Pushes and Pull requests.
4. Click Add webhook. GitHub sends a test message, and Flowmaps shows Connected.

You need to be an admin of the repository to add a webhook.

Good to know

• A card that follows git shows a small git icon and can't be dragged by hand on the board, so GitHub and your board always agree.
• Moves from GitHub show up in Activity as GitHub · username.
• Flowmaps checks GitHub's signature on every message, so nobody else can move your cards.
• Set up again makes a new secret (paste it into the same webhook in GitHub). Disconnect stops it; also delete the webhook in GitHub.