Crowsnest

An iOS widget built with SwiftUI and WidgetKit, Apple’s framework for home screen widgets, that keeps your open pull requests and their CI status one glance away so you can skip opening GitHub.

Quick Start

Get from a fresh clone to a working widget in five steps:

1. Clone this repo and open the project in Xcode. Replace YOUR-ORG with your GitHub account:

git clone [email protected]:YOUR-ORG/ios-widget.git
cd ios-widget
open ios-widget.xcodeproj

2. Select an iPhone 18 simulator (iOS 26.2) as the run destination.
3. Build and run with Cmd+R. On first launch the app asks for a token. Paste a classic GitHub Personal Access Token (PAT) with the repo scope. The app validates it against GitHub before saving.
4. Add the widget. Long-press the home screen, tap Edit, then Add Widget. Search “Crowsnest” and pick the PRPreview widget.
5. Pull to refresh inside the app. The widget then refreshes on its own every 15 minutes.

Installation

Requirements:

• Xcode 26 (the project targets the iOS 26.2 SDK)
• A simulator or device running iOS 26.2
• A GitHub account with a classic PAT that has the repo scope

Build from the command line:

xcodebuild build -scheme ios-widget -destination 'generic/platform=iOS Simulator'

Run the unit test suite. The scheme’s Testable points at the ios-widgetTests target. Pick a simulator name that exists on your machine:

xcodebuild test -scheme ios-widget -destination 'platform=iOS Simulator,name=iPhone 18'

To build for a physical device, sign with your development team:

xcodebuild build -scheme ios-widget -destination 'generic/platform=iOS' -allowProvisioningUpdates

The tests use the Swift Testing framework (import Testing), not XCTest.

Usage

How it works

Crowsnest is a two-bundle app. The main app owns login and the PR list. The widget extension renders the lock screen. The two never talk directly. They share data through an App Group, the shared container that both bundles can read.

1. Configure. The app shows a token screen until you enter a valid PAT. On save, TokenStore writes the token to the Keychain and mirrors a copy into the shared App Group container, so the widget can read it without a shared Keychain access group.
2. Refresh. Pull to refresh, or let the app’s background transition trigger it. WidgetRefreshCoordinator fetches from the GitHub GraphQL API (GraphQL, GitHub’s typed query API), writes a PRCacheData to the App Group, then calls WidgetCenter.reloadAllTimelines().
3. Render. The widget provider builds a timeline entry from token, cache, and fetch outcome, then shows a queue tile. A failed fetch never renders as “all caught up”. It renders as an error entry instead.

What the widget shows