GitHub Sync
GitHub Sync connects Ironspire to your GitHub repositories using a Personal Access Token (PAT). Once connected, it pulls in pull requests, issues, releases and reviews, then uses that data to auto-populate your Blueprint project structure.
Setting up your token
- Open Settings (click the gear icon in the status bar or press Ctrl+,)
- Navigate to the GitHub section
- Click Connect GitHub account
- Paste your GitHub Personal Access Token
The token is stored using Electron's safeStorage API, which encrypts it with your operating system's credential store (Windows DPAPI, macOS Keychain or Linux libsecret). The token is never stored in plain text on disk.
Required token scopes
Your PAT needs the following permissions:
| Scope | Why it is needed |
|---|---|
| repo | Read access to repositories, pull requests, issues and releases |
| read:org | List organisation repositories (if your project is in an org) |
To create a token, go to GitHub Settings > Developer settings > Personal access tokens and generate a new token (classic) with the scopes above. Fine-grained tokens also work as long as they grant read access to the target repository's contents, issues, pull requests and releases.
Never share your Personal Access Token. If you suspect it has been compromised, revoke it immediately from GitHub and generate a new one in Ironspire Settings.
Token display and management
Once saved, your token appears masked in the GitHub Settings section (e.g., ghp_****...****). You can:
- Test connection: verify the token works and see your GitHub username
- Revoke: remove the token from Ironspire's secure storage. This does not revoke the token on GitHub; do that separately if needed.
What gets synced
GitHub Sync fetches four types of data from your connected repository:
| Data type | What is stored | Used for |
|---|---|---|
| Pull requests | Title, state, author, dates, labels, merge status | Blueprint plan generation, agent context |
| Issues | Title, state, labels, assignees, milestone | Blueprint task awareness, backlog context |
| Releases | Tag, title, body, date, draft/prerelease status | Milestone timeline enrichment |
| Reviews | PR review comments, status, reviewer | Code quality context for agents |
All data is stored in a per-profile SQLite database (github_intel.db) using WAL mode for concurrent read performance. The database is registered with the ShutdownManager so it closes cleanly when the app exits or the profile changes.
Sync behaviour
Incremental updates
After the initial full sync, subsequent syncs only fetch records updated since the last sync timestamp. This keeps API usage low and sync times fast, even for repositories with thousands of issues and pull requests.
Polling intervals
| Context | Interval |
|---|---|
| Foreground (app is focused) | Every 5 minutes |
| Background (app is minimised or another profile is active) | Every 30 minutes |
| Manual | Click the refresh button in the Git Intelligence section header |
You can trigger a manual sync at any time. The refresh button shows a spinning indicator while the sync is in progress.
Rate limit awareness
GitHub's API allows 5,000 requests per hour for authenticated users. Ironspire monitors the remaining request count from each API response. When fewer than 100 requests remain, the sync pauses until the rate limit window resets. A status message appears in the Git Intelligence section when rate limiting is active.
Incremental sync typically uses 4 - 8 API requests per cycle (one per data type, plus pagination if needed). Under normal usage you will never approach the rate limit.
Blueprint auto-population
The most powerful feature of GitHub Sync is automatic Blueprint population. When sync data is available, the Blueprint Population Service maps GitHub data to the Blueprint hierarchy:
Mapping rules
| GitHub source | Blueprint level | How it maps |
|---|---|---|
| Semver tags | Milestone | Each tag becomes a milestone with its version, date and commit range |
| Commit types | Phase | Conventional commit prefixes (feat, fix, refactor, etc.) are grouped into phases within each milestone |
| Pull requests | Plan | Each merged PR becomes a plan with its title, description and linked commits |
| Commits | Task | Individual commits within a PR become tasks, linked to their parent plan |
How it works
- GitHub Sync fetches the latest data
- The Blueprint Population Service compares synced data against existing Blueprint items
- New milestones, phases, plans and tasks are created for any data that does not already have a corresponding Blueprint entry
- Existing Blueprint items are not modified or overwritten
This means you can freely edit Blueprint items after they are auto-populated. Manual changes are preserved across future syncs.
Source and confidence badges
Auto-populated Blueprint items carry two visual indicators:
- Source badge: shows "GitHub" to distinguish auto-populated items from manually created ones
- Confidence badge: indicates how reliable the mapping is (High for direct matches like tag-to-milestone, Medium for inferred mappings like commit-type-to-phase)
These badges appear in the Progress panel next to each Blueprint item.
Sync submodules
Internally, GitHub Sync is divided into four submodules that run independently:
| Submodule | Responsibility |
|---|---|
| sync-pulls | Fetches open and recently closed pull requests |
| sync-issues | Fetches open and recently updated issues |
| sync-releases | Fetches published releases and drafts |
| sync-reviews | Fetches review comments for synced pull requests |
Each submodule tracks its own "last synced" timestamp, so a failure in one does not block the others. If sync-reviews fails (e.g., due to a network error), pull requests, issues and releases continue syncing normally.
Data storage
All synced data lives in a per-profile SQLite database named github_intel.db, stored alongside your profile's other data files. The database uses WAL (Write-Ahead Logging) mode for concurrent read performance, meaning the UI can read from the database while a background sync writes new data without contention.
The database is registered with Ironspire's ShutdownManager. When you close the app, switch profiles or trigger an E-STOP, the database connection is closed cleanly to prevent corruption. If the app crashes unexpectedly, WAL mode ensures the database remains in a consistent state on next launch.
Database size depends on the repository. A project with 500 pull requests, 1,000 issues and 50 releases typically occupies 2 - 5 MB on disk.
Troubleshooting
Common issues and their solutions:
| Problem | Cause | Fix |
|---|---|---|
| Sync never completes | Invalid or expired token | Revoke and re-enter your PAT in Settings |
| Missing pull requests | Token lacks repo scope | Generate a new token with the correct scopes |
| "Rate limited" message | Too many API requests in the current hour | Wait for the rate limit window to reset (shown in the status message) |
| Stale data after force-push | Incremental sync missed the rewritten history | Click the manual refresh button to trigger a full re-sync |
Disconnecting
To remove GitHub integration:
- Open Settings > GitHub
- Click Revoke next to your masked token
- Confirm the removal
This removes the token from Ironspire's secure storage and stops all sync activity. Your local github_intel.db database is retained so previously synced data remains available. Delete the database file manually if you want a clean slate.