LanesLanes
Docs/Desktop/Integrations/GitHub Integration

GitHub Integration

Connect Lanes to GitHub to import issues, push results back, and reach GitHub from your agent via the Lanes MCP.

Lanes connects to GitHub so you can pull issues into the local board, work on them with an agent in a worktree, and post the result back to GitHub when you're done. The same connection also gives the Lanes Desktop MCP server a GitHub tool surface, so Claude Code or Codex can do all of this from a chat prompt without you copying URLs around.

Connecting GitHub

Open Lanes, go to Settings, then GitHub, and click Connect. Lanes opens your browser to the GitHub OAuth screen; once you approve, the browser redirects back to a local loopback URL and the settings page flips to Connected as <your handle>.

Behind the scenes:

  • The OAuth flow is brokered by the Lanes API (it holds the client_secret).
  • Scopes requested: repo and read:user. The first lets Lanes list and create issues; the second is the username smoke-check after connect.
  • The access token is stored locally in integrations.json inside the Lanes data directory and never leaves your machine.
  • GitHub access tokens do not expire, so there is no refresh flow to worry about. A revoked token surfaces as a 401 on the next call.

To disconnect, click Disconnect on the same settings page. Lanes wipes the token from integrations.json; you can reconnect at any time.

Reconnecting After a Revoked Token

If your GitHub token is revoked (for example, you rotated it from GitHub's settings), the next API call will fail with a 401. Since v0.41, Lanes catches that case and surfaces a one-click Reconnect banner in the integration's settings page and on any UI that depends on the connection (the import dialog, the issue's external link badge). Click it to re-run the OAuth flow without losing your local data.

Earlier builds failed silently when this happened; if you saw mysterious "could not fetch" errors on imported issues, this is the fix.

Importing an Issue

From any project view in Lanes, click Import from GitHub in the header. The import dialog shows:

  1. A repo picker of every repo you can access (owner, collaborator, or organization member), sorted by most-recently-pushed. Type to filter.
  2. The first 50 open issues in the selected repo, newest first. Pull requests are filtered out automatically.
  3. A search box that hits GitHub's search API. When you type a pure number (#9 or 9), the exact-match issue is pinned to the top of the results even if it would otherwise fall off the list.

Click an issue to import it. Lanes creates a draft on your board with the issue's title and body copied over, plus a marker line in the description linking back to the original GitHub URL. The new Lanes issue carries the external* metadata that powers the external link badge in the issue detail panel.

Refreshing an Imported Issue

Each imported issue shows an external link badge in its detail panel. The badge has an open button (jumps to the GitHub issue) and a refresh button. Refresh re-fetches the issue from GitHub and overwrites the local title and description with the upstream version — useful if the ticket got edited after import.

If you made local edits since the last refresh, Lanes warns before overwriting them. You can keep the local copy or accept the upstream version.

From the Agent (via MCP)

Once GitHub is connected in settings, every lanes_github_* tool on the Lanes Desktop MCP server starts working. The agent can:

  • List or search issues in any of your repos.
  • Read a specific issue by number.
  • Open new issues — useful for spinning off a Lanes-only sub-task into a tracked upstream ticket.
  • Post comments on issues or pull requests — GitHub uses the same endpoint for both, so a single tool covers both cases.

Example prompts:

  • "Import GitHub issue lanes-sh/core#42 into Lanes and start a session on it in a fresh worktree."
  • "Comment back on lanes-sh/core#42 with the PR URL once the session lands."
  • "Open a new GitHub issue on lanes-sh/core titled 'follow-up: rate limiting' with these details from the session."

The agent reads the OAuth token from integrations.json directly — you do not paste it anywhere. The skill at plugins/lanes-desktop/skills/github-lanes-bridge/SKILL.md (ships with the lanes-desktop Claude Code plugin) walks an agent through the full import → execute → push loop and handles dedup, marker lines, and field mapping for you.

Scope Limits

A few things to know about what Lanes can and can't do via GitHub:

  • Pull requests are not exposed via MCP today. PR creation in Lanes happens through the local gh CLI from inside a session. Commenting on a PR works through lanes_github_comment_on_issue (same endpoint).
  • Labels are by name, not ID. When the agent creates an issue, it passes label names ("bug", "area:auth") — GitHub resolves them server-side.
  • Rate limits apply. lanes_github_search_issues hits the GitHub search API, which is rate-limited to 30 requests per minute on the authenticated tier. If you batch-import a huge backlog, expect the agent to pace itself.

For the agent-side details and the full tool reference, see Lanes Desktop MCP.