Connect and Authenticate
Connecting Daintree to a code forge: choosing a provider, the global and per-project settings, the GitHub token scopes that are actually required, credential validation, and what happens when a token expires or you hit a rate limit.
Provider settings
Forge configuration lives in Settings > Code Forge. A dropdown at the top of the tab switches between sections: General, and one section per registered provider. Each provider section renders a credential form built from the fields that provider declares.
General
The General section holds the global default, a view of how the current project resolves, and the forge audit log.
Default forge provider sets the provider used for newly opened projects. The default option is No global default (auto-detect from hostname), which leaves hostname matching in charge. Each registered provider appears below it, showing the hostnames it matches.
Active project routing lists the current project's git remotes and shows, for each one, which provider it resolves to and why. Each row carries a badge:
| Badge | Meaning |
|---|---|
| Override | Resolved from this project's provider override. |
| Default | Resolved by your global default provider. |
| Hostname | Resolved by matching the remote's hostname. |
| No match | No provider resolves this remote. Check the override and the global default first: a fail-closed explicit choice lands here too, not just an unknown hostname. |
If you're ever unsure why a project is or isn't talking to a forge, this table is the place to check.
Forge audit log
Below the routing table, Record forge provider calls appends a record each time a forge provider method is invoked (list, get, assign, validate) with redacted argument summaries. The viewer beside it shows the records, with copy, export and clear controls, plus an anomaly snapshot. It's there for triaging a slow provider or a cluster of failures, not for everyday use, and it's off unless you turn it on.
Per-project override
To override forge behavior for a single project, open Project Settings and go to the Code Forge tab. Two settings live here.
Forge remote selects which git remote Daintree uses for issues, PRs, and pulse data. The default, Auto-detect (origin), keeps the standard behavior: Daintree prefers remotes a registered provider can actually parse, ranked by name preference then git's own listing order. The other options list each configured remote with its name and owner/repo label. Change this when origin points to a fork and you'd rather track the upstream repository. The setting is honored in toolbar issue and PR resolution as well as in worktree linkage.
Forge provider pins the project to a specific provider. The default, Auto-detect, leaves provider selection to the global default and hostname matching. Set it explicitly when matching picks the wrong provider, or when a remote's hostname doesn't make the right provider obvious.
forgeRemote fails closed too. If the remote you named is later renamed or removed, resolution reports the missing remote instead of quietly falling back to origin. Forge resolution backs mutations (assign, close, merge), so substituting a different repository for the one you named could redirect a write to a fork. A dark toolbar is a prompt to fix the setting; a write to the wrong repo is not recoverable.GitHub provider
The GitHub provider is the one that ships with Daintree. Connecting it takes a single personal access token.
Personal access token
Open Settings > Code Forge, select GitHub, and find the Personal access token block. The token covers repository statistics, issue and PR detection, and linking worktrees to issues and PRs. It also means you don't need the gh CLI configured for any of these features.
Paste a token into the field. The placeholder shows the two accepted formats, ghp_... or github_pat_.... Use the buttons beside it:
- Test validates the token against GitHub without saving it. It reports Token valid, click Save to store it so you can confirm before storing.
- Save stores the token and reports Token saved. The sidebar and toolbar refresh as soon as it's accepted, with no restart needed.
- Clear token removes a stored token. It only appears when one is saved.
Tokens are stored locally in Daintree's config, keyed by provider in a forge credentials map rather than under a GitHub-specific key. A GitHub connected indicator confirms a working token. Nothing is sent to Daintree. See Security & Privacy for the full storage model.
Required scopes
A second block, Create a new token, has a Create Token on GitHub button that opens GitHub's token page with the right scopes prefilled. A classic personal access token needs:
repo: access repository data (issues, PRs, statuses, and private repositories)read:org: read organization membership; organization access can also depend on token approval and SSO policy
For a fine-grained token, select the intended owner and repositories, then grant permissions for the features you use. Reading and writing issues requires Issues permission; PRs and reviews require Pull requests; repository content and merge operations can require Contents; status data may require Commit statuses. Choose read access for browsing and write access only for operations you intend the Assistant to perform. Metadata access alone does not grant access to private issue or PR data. Consult GitHub’s endpoint permission reference for each operation.
A successful token test verifies the token, not every repository permission or organization policy. Fine-grained tokens may need organization approval, and organizations can impose expiration limits. Follow GitHub’s token management guidance when selecting repositories, expiration and organization access.
This token authenticates Daintree’s forge API requests. Git fetch, pull and push use your Git transport credentials, such as an SSH key or credential helper. A working forge connection does not prove that Git can push to the remote.
Token resilience and rate limits
When the connection to the forge fails, the integration degrades rather than breaking.
When your token expires or is revoked, a banner appears reading GitHub token expired with the line Reconnect to restore issue, PR, and repository data and a Reconnect to GitHub button, which takes you to Settings > Code Forge > GitHub. Personal access tokens expire on a schedule; Daintree surfaces that clearly instead of quietly failing to fetch.
Inside the issues and PR panel, a token error shows its own inline banner with a Settings button that opens the same place. The panel keeps showing the last results it fetched in the meantime.
For transient network errors, Daintree retries quietly in the background with exponential backoff. Token and rate-limit errors aren't retried this way, since retrying wouldn't help: a rate limit is waited out against its reset time instead.