ShipGaurd

• 

  ARCHITECTURE DIAGRAM

Category: The Taskmaster

ShipGuard is built for the Taskmaster track. It turns a real TestFlight report into an independently completed engineering workflow.

Inspiration

Building iOS apps is one of the things I enjoy most. But after I distribute a TestFlight build, turning beta-tester feedback into a reliable fix is still highly manual.

A tester reports a crash or broken screen. I need to find the report, understand the issue, search the repository, inspect recent changes, form a hypothesis, write a fix, create a branch, run Xcode, and prepare a pull request.

For small bugs, this coordination work can take longer than the actual code change.

That led to a simple question:

What if TestFlight feedback could start the debugging process itself?

I did not want another coding assistant that waits for a developer to describe the problem. I wanted an autonomous first responder that can take the report, gather evidence, validate a safe fix, and hand the developer a reviewable pull request.

That is ShipGuard.

What it does

ShipGuard turns TestFlight screenshot feedback and crash submissions into evidence-based, Xcode-validated GitHub pull requests.

When new feedback arrives, ShipGuard automatically:

• Retrieves and deduplicates feedback from the App Store Connect API
• Maps the iOS app to its connected GitHub repository
• Uses Google ADK and Gemini to investigate the real codebase
• Searches relevant code, reads source files, and examines recent commits
• Separates facts from hypotheses and assigns a confidence score
• Proposes the smallest supported code change
• Applies deterministic patch and risk checks
• Validates that exact patch with a real xcodebuild on a hosted macOS runner
• Stops safely when evidence is weak, validation fails, or risk is too high
• Creates a GitHub pull request only after validation succeeds

ShipGuard never merges its own pull requests. The developer always makes the final engineering decision.

How I built it

ShipGuard is an event-driven autonomous pipeline running on Google Cloud.

Cloud Scheduler checks App Store Connect for new TestFlight feedback. The sync service normalizes and deduplicates each report, stores it in Firestore, and publishes one event per new item to the shipguard-feedback Pub/Sub topic.

The shipguard-feedback-sub subscription delivers that event to a Cloud Run worker. This worker uses Google ADK with Gemini 3.5 Flash through Vertex AI to investigate the repository and propose a minimal fix.

The agents have read-only GitHub tools. They can inspect the repository tree, search code, read files, and inspect recent commits, but they cannot write to GitHub. All branch and pull-request creation is handled later by deterministic backend code.

Before validation, ShipGuard records the exact base commit and calculates a SHA-256 fingerprint for the proposed patch.

Cloud Run runs Linux, while Xcode requires macOS. ShipGuard creates an isolated validation branch and triggers shipguard-validation.yml on a hosted GitHub Actions macOS runner. That runner performs a real Xcode build.

Cloud Scheduler then checks the GitHub Actions result asynchronously. When validation reaches a terminal state, ShipGuard publishes a shipguard-validation-complete event. The shipguard-validation-complete-sub subscription triggers the final publication worker.

Before creating a pull request, ShipGuard re-checks:

• The base branch has not advanced
• The patch fingerprint still matches
• The resulting changed-file hashes still match
• The patch meets the project risk policy
• The real Xcode validation passed

Only then does it create a deterministic shipguard/fix-* branch and open a pull request.

A separate, read-only Next.js dashboard subscribes to Firestore and shows the workflow live:

Detected → Investigating → Fix Generated → Validating → Pull Request Ready

Engineering and safety

ShipGuard is intentionally designed as a production-minded system, not a long-running prompt.

Decoupled workflow

TestFlight syncing, AI investigation, Xcode validation, and PR publication are separate stages connected through Pub/Sub. A slow build, retry, or failed issue does not block new feedback from being collected.

Durable state, not chat memory

Each Gemini step uses a fresh, structured ADK session. Durable state lives in Firestore: projects, feedback, runs, validation jobs, event state, and processing locks. This makes progress observable, resumable, and independent of a chat session.

Idempotency

Pub/Sub is at-least-once, so workers use transactional Firestore locks and idempotent processing. The same feedback event cannot create duplicate work.

Branch identity is based on the base commit SHA and patch fingerprint, so repeated execution maps to the same validated fix rather than creating duplicate branches or pull requests.

Scoped permissions and credentials

GitHub and App Store Connect credentials are stored in Google Secret Manager, not in source code, logs, Firestore, or the dashboard.

Production internal endpoints require Google-signed OIDC authentication. Protected branches are never written to.

Safe failure behavior

ShipGuard does not invent a fix when evidence is weak. It reports needs_more_context.

It reports partial validation when the environment cannot validate meaningfully, rather than claiming success. Builds and tests have timeouts.

If the branch changes, the patch differs, validation fails, or risk is high, ShipGuard stops for human review.

The core principle is simple:

AI proposes → deterministic checks verify → real Xcode validates → developer reviews

AI agents

Agent	Role	Access
ShipGuardAgent	Turns a bug report into structured analysis	No tools
InvestigationAgent	Investigates the repository and gathers evidence	Read-only GitHub tools
FixAgent	Proposes the smallest evidence-based patch	Read-only GitHub tools
ValidationAgent	Explains real build and test results	No tools

Tech stack

Area	Technology
Agent orchestration	Google ADK
AI model	Gemini 3.5 Flash through Vertex AI
Backend	Python, FastAPI, Cloud Run
Events	Cloud Pub/Sub
Scheduling	Cloud Scheduler
State and database	Cloud Firestore
Secrets	Google Secret Manager
TestFlight feedback	App Store Connect API
Repository and pull requests	GitHub API
iOS validation	GitHub Actions hosted macOS runner, Xcode, xcodebuild
Dashboard	Next.js, TypeScript, Firebase Web SDK

Challenges I ran into

The first challenge was making ShipGuard autonomous without making it unsafe.

Letting an LLM generate code and push it directly would have been easy, but unreliable. I addressed this with confidence thresholds, minimal-patch checks, risk classification, protected-branch rules, exact base-commit tracking, patch fingerprints, real build validation, and human review.

The second challenge was iOS validation in the cloud.

Google Cloud Run is Linux, but Xcode requires macOS. I separated reasoning from validation. Google Cloud orchestrates the workflow, while GitHub Actions provides a hosted macOS runner for the real Xcode build.

The third challenge was long-running work.

An Xcode build can take minutes, so Cloud Run should not keep one HTTP request open waiting for it. Pub/Sub, Firestore validation jobs, Cloud Scheduler checks, and continuation events let ShipGuard continue the workflow asynchronously.

Accomplishments I’m proud of

I’m most proud that ShipGuard performs a real end-to-end workflow rather than simulating one.

In the demo, ShipGuard automatically:

Detected TestFlight feedback → investigated a real repository → found supporting evidence → generated a minimal fix → created a validation branch → ran a real Xcode build → verified patch identity → opened a real GitHub pull request

The developer’s computer was not running, and no manual debugging workflow was started.

I’m also proud that the project treats safety as a feature, not an afterthought. ShipGuard does not write to protected branches, does not auto-merge, and does not claim an AI suggestion is validated until the exact patch has passed real Xcode validation.

What I learned

I learned that reliable agents need more than an LLM. Gemini handles investigation and reasoning, but deterministic code controls validation, repository writes, and safety checks.

The most important difference is between an AI suggestion and a fix that has passed a real Xcode build.

What's next

Next, I want to add crash-log analysis, duplicate issue grouping, Crashlytics integration, Slack notifications, configurable approval rules, and authenticated team dashboards.

The goal is simple: reduce the time between a tester finding an issue and a developer receiving a validated fix for review.

Built With

• google-cloud