Skip to content

How to configure the GitHub source

This guide walks you through setting up gtdhelper to show your GitHub pull requests and issues.

Prerequisites

  • gh CLI installed and authenticated (gh auth login)

Steps

1. Create the configuration file

cp scripts/config/github.toml.example ~/.gtdhelper/github.toml

Or create ~/.gtdhelper/github.toml manually:

[[repos]]
name = "owner/repo"
types = ["pull_request", "issue"]

2. Add your repositories

Each [[repos]] entry defines one repository to watch. Add as many as you need:

[[repos]]
name = "myorg/backend"
types = ["pull_request", "issue"]

[[repos]]
name = "myorg/frontend"
types = ["pull_request"]

The types field controls what to fetch:

Value What it fetches
"pull_request" Open pull requests assigned to you or requesting your review
"issue" Open issues assigned to you

If types is omitted, it defaults to ["pull_request"].

3. Verify it works

Restart gtdhelper (or wait for the next 5-minute refresh). Your GitHub items should appear in the overlay.

Check for errors in the gtdhelper logs if nothing shows up — common causes:

  • gh CLI not authenticated: run gh auth login
  • Repository name typo: must be exact owner/repo format
  • No matching items: you have no open PRs/issues assigned to you in that repo

See also