GitHub repo not configured (set github.repo or GITHUB_REPO)

Error message

GitHub repo not configured (set github.repo or GITHUB_REPO)

What it means

Tracker.Init requires a GitHub repository name to construct its API client. The repo is read from the tracker config key github.repo or the GITHUB_REPO environment variable; when both are empty, Init fails with this message so the user knows exactly which setting to add.

Source

Thrown at internal/github/tracker.go:69

	repo := t.getConfig(ctx, "github.repo", "GITHUB_REPO")

	// Try combined owner/repo format: "owner/repo"
	if owner == "" || repo == "" {
		ownerRepo := t.getConfig(ctx, "github.repository", "GITHUB_REPOSITORY")
		if ownerRepo != "" {
			parts := strings.SplitN(ownerRepo, "/", 2)
			if len(parts) == 2 {
				owner = parts[0]
				repo = parts[1]
			}
		}
	}

	if owner == "" {
		return fmt.Errorf("GitHub owner not configured (set github.owner or GITHUB_OWNER)")
	}
	if repo == "" {
		return fmt.Errorf("GitHub repo not configured (set github.repo or GITHUB_REPO)")
	}

	t.client = NewClient(token, owner, repo)

	// Allow custom base URL for GitHub Enterprise
	baseURL := t.getConfig(ctx, "github.url", "GITHUB_API_URL")
	if baseURL != "" {
		t.client = t.client.WithBaseURL(baseURL)
	}

	t.config = DefaultMappingConfig()
	return nil
}

func (t *Tracker) Validate() error {
	if t.client == nil {
		return fmt.Errorf("GitHub tracker not initialized")
	}

View on GitHub (pinned to 71377f2769)

Solutions

Set the environment variable: export GITHUB_REPO="my-repo".
Or set it in the tracker config: `bd config set github.repo my-repo` (or the equivalent config file entry).
Also verify github.owner / GITHUB_OWNER is set, since owner is checked first.
Re-run the initializing command after setting the value.

Example fix

// before
// no config
// after (shell)
export GITHUB_OWNER="my-org"
export GITHUB_REPO="my-repo"

Defensive patterns

Strategy: validation

Validate before calling

repo := os.Getenv("GITHUB_REPO")
if repo == "" { repo = cfg.Get("github.repo") }
if repo == "" { return errors.New("set github.repo or GITHUB_REPO before initializing the GitHub tracker") }

Try / catch

if err := t.Init(ctx); err != nil {
    if strings.Contains(err.Error(), "GitHub repo not configured") { log.Fatal("set GITHUB_REPO env var or github.repo config") }
    return err
}

Prevention

Set GITHUB_OWNER/GITHUB_REPO in your shell profile or CI environment.
Check configuration at startup, before any tracker operation.
Use `bd doctor` or equivalent to verify tracker configuration.

When it happens

Trigger: Calling tracker.Init (or any flow that initializes the GitHub tracker) on a machine/config where neither the github.repo config value nor the GITHUB_REPO env var is set (owner may be set; this error is specifically about repo).

Common situations: Fresh checkout without a .env, running in CI where GITHUB_REPO is not exported, switching trackers (e.g. from bd/local to GitHub) without configuring repo coordinates.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/1512ca5f1b726823. Report an issue: GitHub.