feat(caretaker): implement Cloud Run webhook ingestion service

[chadd28]

Summary

Implements the Cloud Run Webhook Ingestion Service for the Caretaker Agent. The service acts as an entry point for GitHub webhooks, verifies incoming payload signatures, stores new issue entries using Firestore transactions, and publishes sanitized issue metadata to a GCP Pub/Sub topic for downstream processing.

Details

• Server (server.ts): The main Express server (to be hosted on Cloud Run) that receives GitHub issues.opened events, validates their signature, adds the issue to Firestore, and publishes the issue details to Pub/Sub.
• Auth Verification (auth/github.ts): HMAC SHA-256 signature verification helper using node:crypto and a secure timing-safe equality check.
• Store (db/issuesStore.ts): Initializes new issues in Firestore using a transaction.
• Tests: Added issuesStore.test.ts (Firestore mock tests) and github.test.ts (HMAC signature verification tests).

How to Validate

Run unit tests in the service directory:

cd tools/caretaker-agent/cloudrun/ingestion-service
npm install
npx vitest run

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

@galz10

[github-actions]

📊 PR Size: size/L

• Lines changed: 997
• Additions: +994
• Deletions: -3
• Files changed: 12

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new ingestion service for the Caretaker Agent, designed to run on Cloud Run. The service acts as a secure gateway for GitHub webhooks, handling event validation, deduplication via Firestore transactions, and message queuing through Pub/Sub. This infrastructure enables automated downstream triage workflows for incoming GitHub issues.

Highlights

• Webhook Ingestion Service: Implemented a new Express-based service to receive and process GitHub 'issues.opened' webhooks.
• Security & Verification: Added HMAC SHA-256 signature verification using timing-safe equality checks to ensure payload authenticity.
• Data Persistence: Integrated Firestore transactions to reliably store issue metadata and prevent duplicate entries.
• Downstream Integration: Configured Pub/Sub publishing to forward sanitized issue data for further processing.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new Express-based ingestion service for a triage worker, featuring GitHub webhook signature verification, Firestore storage for tracking issues, and Pub/Sub integration. The review feedback highlights three critical security and reliability improvements: validating the signature length and payload type in the GitHub auth module to prevent crashes and DoS attacks, escaping the issue body to mitigate prompt injection vulnerabilities, and checking the return value of the issue creation transaction to prevent duplicate Pub/Sub messages.

[galdawave]

[P1] Production anti-pattern.
Running tsx (or ts-node) in a production container introduces significant memory overhead and startup latency. Add a "build": "tsc" script to package.json and run the compiled JavaScript here instead.

Suggested change

	RUN npm run build
	CMD ["node", "dist/server.js"]

[galdawave]

[P0] Dual-write failure state permanently drops retried webhooks.
If the Firestore write succeeds but the Pub/Sub publish fails, the server returns a 500 error, and GitHub will retry. On the retry, createIssue returns false (since the document already exists), causing the endpoint to return 200 early and skip the Pub/Sub publish entirely. The issue will never be processed downstream. You should publish to Pub/Sub even if the DB document exists (assuming downstream is idempotent) or rely entirely on Pub/Sub and let the downstream worker deduplicate.

[galdawave]

[P2] Unsafe header cast.
Express headers can be an array (string[]) if multiple headers with the same name are sent. If an array is passed, downstream checks like signature.length will evaluate the array length rather than string length.

Suggested change

	const signature = req.headers['x-hub-signature-256'] as string | undefined;
	const header = req.headers['x-hub-signature-256'];
	const signature = Array.isArray(header) ? header[0] : header;

[galdawave]

[P2] Blind type casting.
The explicit cast as GitHubWebhookPayload bypasses runtime safety. At minimum, we should validate the presence of payload.issue.number and payload.repository.full_name before assuming the structure exists to avoid unexpected undefined errors downstream.

[galdawave]

[P2] Misleading variable name / Missing sanitization.
This is not actually sanitized. If a user maliciously includes </untrusted_context> in their GitHub issue description, they will break out of the LLM context wrapper downstream. Rename this to wrappedBody to be accurate, or implement actual tag escaping/stripping.

[galdawave]

[P0] Missing core unit tests.
The PR introduces complex routing, orchestrating validation, DB writes, and Pub/Sub publishing in server.ts without a corresponding server.test.ts. This violates the testing standard criteria. Please add tests that mock the Firestore and Pub/Sub clients to verify the endpoint behavior.

[rsloane82-create]

Public service announcement

…

On Thu, Jun 25, 2026, 21:01 Richard Sloane ***@***.***> wrote: Why won't you talk to me on the phone On Thu, Jun 25, 2026, 20:25 Chad ***@***.***> wrote: > ***@***.**** commented on this pull request. > ------------------------------ > > In tools/caretaker-agent/cloudrun/ingestion-service/app.ts > <#28015 (comment)> > : > > > + } catch (error) { > + console.error('Error processing webhook:', error); > + const message = error instanceof Error ? error.message : 'Unknown error'; > + return res.status(500).json({ status: 'error', message }); > + } > +}); > + > +app.use( > + ( > + err: unknown, > + req: express.Request, > + res: express.Response, > + next: express.NextFunction, > + ) => { > + // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion > + const error = err as { status?: number; message?: string }; > > resolved! Used property checking ('status' in err) > > — > Reply to this email directly, view it on GitHub > <#28015?email_source=notifications&email_token=BUZGG3C7OBCEIVRXATKY2PL5BW7JNA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTINJXGU4TIMZRHE32M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#discussion_r3478465927>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/BUZGG3BNVJLHZ2GMHKUZOGT5BW7JNAVCNFSNUABFKJSXA33TNF2G64TZHM4TMOBRHE3TEMJWHNEXG43VMU5TINRZGQ3TMMZTHA2KC5QC> > . > You are receiving this because you are subscribed to this thread.Message > ID: ***@***.***> >

[gemini-cli]

Hi there! Thank you for your interest in contributing to Gemini CLI.

To ensure we maintain high code quality and focus on our prioritized roadmap, we only guarantee review and consideration of pull requests for issues that are explicitly labeled as 'help wanted'.

This PR will be closed in 7 days if it remains without that designation. We encourage you to find and contribute to existing 'help wanted' issues in our backlog! Thank you for your understanding.