feat: route signed GitHub activity into bound pods

Add a flag-guarded GitHub App webhook with raw-body signature validation,
explicit repository-to-pod binding, permanent delivery deduplication, and
closed-catalog activity cards. Complete a matching task when its linked PR
merges. Keep provider prose outside agent-visible content pending ruling.

Written by Sprint Impl, a Commonly agent

Co-authored-by: sprint-impl <WyJzcHJpbnQtaW1wbCIsImRlZmF1bHQiXQ@agents.commonly.invalid>
Agent-Model: codex/gpt-6-sol/medium

Author: lilyshen0722

backend/__tests__/unit/routes/github.webhook.test.js

@@ -0,0 +1,117 @@
+const crypto = require('crypto');
+const express = require('express');
+const request = require('supertest');
+
+const mockBinding = jest.fn();
+const mockCreateReceipt = jest.fn();
+const mockHandle = jest.fn();
+jest.mock('../../../services/githubGigService', () => ({
+  githubLocation: jest.requireActual('../../../services/githubGigService').githubLocation,
+  boundPodForGithubEvent: (...args) => mockBinding(...args),
+}));
+jest.mock('../../../models/GithubGigDelivery', () => ({ create: (...args) => mockCreateReceipt(...args) }));
+jest.mock('../../../services/installable/eventHandlers', () => ({
+  eventHandlers: { 'github.gig': (...args) => mockHandle(...args) },
+}));
+
+const route = require('../../../routes/webhooks/github');
+const app = express();
+app.use('/api/webhooks/github', express.raw({ type: 'application/json' }));
+app.use(express.json());
+app.use('/api/webhooks/github', route);
+
+const payload = {
+  action: 'opened', installation: { id: 123 },
+  repository: { owner: { login: 'Team-Commonly' }, name: 'commonly' },
+  pull_request: { number: 42, title: 'External text' },
+};
+const deliver = (body, overrides = {}) => {
+  const signature = `sha256=${crypto.createHmac('sha256', 'secret').update(body).digest('hex')}`;
+  return request(app).post('/api/webhooks/github')
+    .set('Content-Type', 'application/json')
+    .set('X-Hub-Signature-256', signature)
+    .set('X-GitHub-Event', 'pull_request')
+    .set('X-GitHub-Delivery', '123e4567-e89b-12d3-a456-426614174000')
+    .set(overrides)
+    .send(body);
+};
+
+beforeEach(() => {
+  process.env.GITHUB_GIG_WEBHOOK_SECRET = 'secret';
+  process.env.GITHUB_GIG_ENABLED = 'true';
+  mockBinding.mockReset().mockResolvedValue(null);
+  mockCreateReceipt.mockReset().mockResolvedValue({});
+  mockHandle.mockReset().mockResolvedValue(undefined);
+});
+afterAll(() => {
+  delete process.env.GITHUB_GIG_WEBHOOK_SECRET;
+  delete process.env.GITHUB_GIG_ENABLED;
+});
+
+test('missing and invalid signatures return 401 before parsing or lookup', async () => {
+  const missing = await request(app).post('/api/webhooks/github')
+    .set('Content-Type', 'application/json').send('{bad json');
+  const invalid = await deliver('{bad json', { 'X-Hub-Signature-256': 'sha256=0000' });
+  expect(missing.status).toBe(401);
+  expect(invalid.status).toBe(401);
+  expect(missing.text).toBe('');
+  expect(mockBinding).not.toHaveBeenCalled();
+  expect(mockCreateReceipt).not.toHaveBeenCalled();
+});
+
+test('signature covers the raw bytes, including whitespace', async () => {
+  const body = JSON.stringify(payload, null, 2);
+  const response = await deliver(body);
+  expect(response.status).toBe(204);
+  expect(mockBinding).toHaveBeenCalledWith({
+    installationId: '123', owner: 'Team-Commonly', repo: 'commonly', number: '42',
+  });
+  expect(mockCreateReceipt).not.toHaveBeenCalled();
+});
+
+test('an unbound App-wide delivery is silent and does not write a receipt', async () => {
+  const response = await deliver(JSON.stringify(payload));
+  expect(response.status).toBe(204);
+  expect(mockBinding).toHaveBeenCalledTimes(1);
+  expect(mockCreateReceipt).not.toHaveBeenCalled();
+  expect(mockHandle).not.toHaveBeenCalled();
+});
+
+test('a bound delivery is claimed once and replay does not post twice', async () => {
+  mockBinding.mockResolvedValue('aaaaaaaaaaaaaaaaaaaaaaaa');
+  mockCreateReceipt.mockResolvedValueOnce({}).mockRejectedValueOnce(Object.assign(new Error('duplicate'), { code: 11000 }));
+  const first = await deliver(JSON.stringify(payload));
+  await new Promise((resolve) => setImmediate(resolve));
+  const replay = await deliver(JSON.stringify(payload));
+  expect(first.status).toBe(204);
+  expect(replay.status).toBe(204);
+  expect(mockCreateReceipt).toHaveBeenCalledTimes(2);
+  expect(mockHandle).toHaveBeenCalledTimes(1);
+});
+
+test('checks remain off until checks:read is granted', async () => {
+  const check = { ...payload, action: 'completed', check_run: { conclusion: 'failure', pull_requests: [{ number: 42 }] } };
+  const response = await deliver(JSON.stringify(check), { 'X-GitHub-Event': 'check_run' });
+  expect(response.status).toBe(204);
+  expect(mockBinding).not.toHaveBeenCalled();
+});
+
+test.each([
+  ['pull_request_review', 'submitted', { pull_request: { number: 42 }, review: { state: 'approved', body: 'outsider' } }],
+  ['issues', 'opened', { issue: { number: 42, title: 'outsider' } }],
+  ['issues', 'closed', { issue: { number: 42, body: 'outsider' } }],
+])('%s %s routes only when bound', async (eventType, action, fields) => {
+  mockBinding.mockResolvedValue('aaaaaaaaaaaaaaaaaaaaaaaa');
+  const body = JSON.stringify({
+    action, installation: payload.installation, repository: payload.repository, ...fields,
+  });
+  const response = await deliver(body, {
+    'X-GitHub-Event': eventType,
+    'X-GitHub-Delivery': `123e4567-e89b-12d3-a456-42661417400${action === 'closed' ? 1 : eventType === 'issues' ? 2 : 3}`,
+  });
+  await new Promise((resolve) => setImmediate(resolve));
+  expect(response.status).toBe(204);
+  expect(mockBinding).toHaveBeenCalledTimes(1);
+  expect(mockCreateReceipt).toHaveBeenCalledTimes(1);
+  expect(mockHandle).toHaveBeenCalledWith(expect.objectContaining({ eventType }));
+});

backend/__tests__/unit/routes/integrations.githubGigBinding.test.js

@@ -0,0 +1,57 @@
+const express = require('express');
+const request = require('supertest');
+const mongoose = require('mongoose');
+const { MongoMemoryServer } = require('mongodb-memory-server');
+
+jest.mock('../../../middleware/auth', () => (req, _res, next) => { req.user = { id: 'bbbbbbbbbbbbbbbbbbbbbbbb' }; next(); });
+jest.mock('../../../middleware/adminAuth', () => (req, res, next) => (
+  req.get('x-admin') === 'yes' ? next() : res.status(403).end()
+));
+
+let mongod;
+let app;
+let Pod;
+let Integration;
+let GithubGigBinding;
+const podId = new mongoose.Types.ObjectId();
+const adminId = new mongoose.Types.ObjectId();
+
+beforeAll(async () => {
+  mongod = await MongoMemoryServer.create();
+  await mongoose.connect(mongod.getUri());
+  Pod = require('../../../models/Pod');
+  Integration = require('../../../models/Integration');
+  GithubGigBinding = require('../../../models/GithubGigBinding');
+  app = express();
+  app.use(express.json());
+  app.use('/api/integrations', require('../../../routes/integrations'));
+  await Pod.create({ _id: podId, name: 'Build', createdBy: adminId, members: [adminId] });
+});
+afterAll(async () => { await mongoose.disconnect(); if (mongod) await mongod.stop(); });
+
+test('only an admin can bind and unbind a connected App repository to a real pod', async () => {
+  const row = await Integration.create({
+    installationId: '7654321', type: 'github-app', scope: 'user', status: 'connected',
+    config: { installationId: '7654321', owner: 'Team-Commonly', repo: 'commonly' },
+    createdBy: adminId, isActive: true,
+  });
+  const path = `/api/integrations/github-app/${row._id}/gig-pod`;
+  const denied = await request(app).put(path).send({ podId: String(podId) });
+  expect(denied.status).toBe(403);
+  expect(await GithubGigBinding.countDocuments()).toBe(0);
+
+  const missing = await request(app).put(path).set('x-admin', 'yes').send({ podId: String(new mongoose.Types.ObjectId()) });
+  expect(missing.status).toBe(404);
+  const bound = await request(app).put(path).set('x-admin', 'yes').send({ podId: String(podId) });
+  expect(bound.status).toBe(200);
+  expect(String((await GithubGigBinding.findOne({ installationId: '7654321' })).podId)).toBe(String(podId));
+
+  const secondRepo = await request(app).put(path).set('x-admin', 'yes')
+    .send({ podId: String(podId), owner: 'Team-Commonly', repo: 'another-repo' });
+  expect(secondRepo.status).toBe(200);
+  expect(await GithubGigBinding.countDocuments({ installationId: '7654321' })).toBe(2);
+
+  const unbound = await request(app).delete(path).set('x-admin', 'yes');
+  expect(unbound.status).toBe(204);
+  expect(await GithubGigBinding.countDocuments()).toBe(1);
+});

backend/__tests__/unit/services/githubGigService.test.js

@@ -0,0 +1,72 @@
+const mockIntegrationFind = jest.fn();
+const mockTaskUpdate = jest.fn();
+const mockPost = jest.fn();
+const mockEmit = jest.fn();
+jest.mock('../../../models/GithubGigBinding', () => ({ findOne: (...args) => mockIntegrationFind(...args) }));
+jest.mock('../../../models/Task', () => ({ findOneAndUpdate: (...args) => mockTaskUpdate(...args) }));
+jest.mock('../../../services/agentIdentityService', () => ({ getOrCreateAgentUser: jest.fn().mockResolvedValue({ _id: 'bot' }) }));
+jest.mock('../../../services/agentMessageService', () => ({ _postToTarget: (...args) => mockPost(...args) }));
+jest.mock('../../../services/taskEventService', () => ({ emitTaskUpdated: (...args) => mockEmit(...args) }));
+
+const {
+  githubLocation, boundPodForGithubEvent, buildGithubGigCard,
+  completeTaskForMergedPull, handleGithubGig,
+} = require('../../../services/githubGigService');
+
+const podId = 'aaaaaaaaaaaaaaaaaaaaaaaa';
+const location = { installationId: '7654321', owner: 'Team-Commonly', repo: 'commonly', number: '42' };
+const payload = {
+  action: 'closed', installation: { id: 7654321 },
+  repository: { owner: { login: 'Team-Commonly' }, name: 'commonly' },
+  pull_request: { number: 42, merged: true, title: '<script>outsider</script>' },
+};
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockPost.mockResolvedValue({ message: { id: 'm1' } });
+  mockTaskUpdate.mockResolvedValue(null);
+});
+
+test('accepts only structural repository coordinates and numeric ids', () => {
+  expect(githubLocation(payload)).toEqual(location);
+  expect(githubLocation({ ...payload, repository: { owner: { login: 'github.com.evil' }, name: 'repo/x' } })).toBeNull();
+  expect(githubLocation({ ...payload, pull_request: { number: '1/../../admin' } })).toBeNull();
+});
+
+test('one indexed connection lookup selects an explicitly bound pod', async () => {
+  mockIntegrationFind.mockReturnValue({ select: () => ({ lean: async () => ({ podId }) }) });
+  expect(await boundPodForGithubEvent(location)).toBe(podId);
+  expect(mockIntegrationFind).toHaveBeenCalledWith(expect.objectContaining({
+    installationId: location.installationId, owner: location.owner, repo: location.repo,
+  }));
+});
+
+test('card excludes outsider text and builds a canonical GitHub URL', () => {
+  const card = buildGithubGigCard('pull_request', payload, location);
+  expect(JSON.stringify(card)).not.toContain('outsider');
+  expect(card.elements[2].href).toBe('https://github.com/Team-Commonly/commonly/pull/42');
+  expect(card.elements[0].children[0].text).toBe('Merged');
+});
+
+test('a merged PR completes only its matching open task and emits a board update', async () => {
+  const task = { taskId: 'TASK-11', status: 'done' };
+  mockTaskUpdate.mockResolvedValue(task);
+  const href = 'https://github.com/Team-Commonly/commonly/pull/42';
+  await completeTaskForMergedPull(podId, href);
+  const [filter, update] = mockTaskUpdate.mock.calls[0];
+  expect(String(filter.podId)).toBe(podId);
+  expect(filter.prUrl).toBe(href);
+  expect(filter.status).toEqual({ $in: ['pending', 'claimed'] });
+  expect(update.$set.status).toBe('done');
+  expect(mockEmit).toHaveBeenCalledWith(podId, task, 'updated');
+});
+
+test('posts a display card while agent-visible content stays fixed', async () => {
+  await handleGithubGig({ eventType: 'pull_request', payload, podId, location });
+  const posted = mockPost.mock.calls[0][0];
+  expect(posted.content).toBe('[GitHub activity]');
+  expect(posted.payload.kind).toBe('gig-card');
+  expect(posted.noOutboundRelay).toBe(true);
+  expect(JSON.stringify(posted.payload)).not.toContain('outsider');
+  expect(mockTaskUpdate).toHaveBeenCalledTimes(1);
+});

backend/models/GithubGigBinding.ts

@@ -0,0 +1,25 @@
+import mongoose, { Document, Model, Schema, Types } from 'mongoose';
+
+/** Explicit opt-in for one App installation/repository to post in one pod. */
+export interface IGithubGigBinding extends Document {
+  installationId: string;
+  owner: string;
+  repo: string;
+  podId: Types.ObjectId;
+  createdBy: Types.ObjectId;
+}
+
+const GithubGigBindingSchema = new Schema<IGithubGigBinding>({
+  installationId: { type: String, required: true },
+  owner: { type: String, required: true },
+  repo: { type: String, required: true },
+  podId: { type: Schema.Types.ObjectId, ref: 'Pod', required: true },
+  createdBy: { type: Schema.Types.ObjectId, ref: 'User', required: true },
+}, { timestamps: true });
+
+GithubGigBindingSchema.index({ installationId: 1, owner: 1, repo: 1 }, { unique: true });
+
+export const GithubGigBinding: Model<IGithubGigBinding> = mongoose.model<IGithubGigBinding>('GithubGigBinding', GithubGigBindingSchema);
+export default GithubGigBinding;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+module.exports = exports["default"]; Object.assign(module.exports, exports);

backend/models/GithubGigDelivery.ts

@@ -0,0 +1,16 @@
+import mongoose, { Document, Model, Schema } from 'mongoose';
+
+/** Permanent replay receipt: manual GitHub redelivery has no 24-hour limit. */
+export interface IGithubGigDelivery extends Document {
+  deliveryId: string;
+  createdAt: Date;
+}
+
+const GithubGigDeliverySchema = new Schema<IGithubGigDelivery>({
+  deliveryId: { type: String, required: true, unique: true },
+}, { timestamps: { createdAt: true, updatedAt: false } });
+
+export const GithubGigDelivery: Model<IGithubGigDelivery> = mongoose.model<IGithubGigDelivery>('GithubGigDelivery', GithubGigDeliverySchema);
+export default GithubGigDelivery;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+module.exports = exports["default"]; Object.assign(module.exports, exports);

backend/models/Task.ts

@@ -87,6 +87,10 @@ const TaskSchema = new Schema<ITask>(
 
 TaskSchema.index({ podId: 1, status: 1 });
 TaskSchema.index({ podId: 1, assignee: 1, status: 1 });
+TaskSchema.index(
+  { podId: 1, prUrl: 1, status: 1 },
+  { partialFilterExpression: { prUrl: { $type: 'string' } } },
+);
 TaskSchema.index({ podId: 1, taskId: 1 }, { unique: true });
 // Partial, NOT sparse: a compound sparse index still indexes any doc where
 // podId is present (i.e. all of them), so the second no-sourceRef task in a

backend/routes/integrations.ts

@@ -13,6 +13,8 @@ const hostedMcpConnectRoutes = require('./hostedMcpConnect');
 // eslint-disable-next-line global-require
 const Integration = require('../models/Integration');
 // eslint-disable-next-line global-require
+const GithubGigBinding = require('../models/GithubGigBinding');
+// eslint-disable-next-line global-require
 const DiscordIntegration = require('../models/DiscordIntegration');
 // eslint-disable-next-line global-require
 const DiscordService = require('../services/discordService');
@@ -267,6 +269,42 @@ router.post('/github-app', writeIntegrationsRateLimit, auth, adminAuth, async (r
   }
 });
 
+// Explicit admin bind for the App-wide activity webhook. Connection creation
+// alone never opts a repository into a pod or agent-visible activity.
+router.put('/github-app/:id/gig-pod', writeIntegrationsRateLimit, auth, adminAuth, async (req: AuthReq, res: Res) => {
+  const podId = String(req.body?.podId || '');
+  const integrationId = String(req.params?.id || '');
+  if (!Types.ObjectId.isValid(podId)) return res.status(400).json({ message: 'Valid podId required' });
+  if (!Types.ObjectId.isValid(integrationId)) return res.status(404).json({ message: 'GitHub App connection not found' });
+  const integration = await Integration.findOne({ _id: integrationId, type: 'github-app', isActive: true, status: 'connected' }).lean();
+  if (!integration) return res.status(404).json({ message: 'GitHub App connection not found' });
+  const owner = String(req.body?.owner || integration.config?.owner || '');
+  const repo = String(req.body?.repo || integration.config?.repo || '');
+  if (!/^[A-Za-z0-9_.-]{1,100}$/.test(owner) || !/^[A-Za-z0-9_.-]{1,100}$/.test(repo)) {
+    return res.status(400).json({ message: 'Valid owner and repo required' });
+  }
+  const pod = await Pod.exists({ _id: new Types.ObjectId(podId) });
+  if (!pod) return res.status(404).json({ message: 'Pod not found' });
+  const binding = await GithubGigBinding.findOneAndUpdate(
+    { installationId: String(integration.installationId), owner, repo },
+    { $set: { podId: new Types.ObjectId(podId) }, $setOnInsert: { createdBy: new Types.ObjectId(String(req.user?.id)) } },
+    { new: true, upsert: true },
+  );
+  return res.json({ binding });
+});
+
+router.delete('/github-app/:id/gig-pod', writeIntegrationsRateLimit, auth, adminAuth, async (req: AuthReq, res: Res) => {
+  const integrationId = String(req.params?.id || '');
+  if (!Types.ObjectId.isValid(integrationId)) return res.status(404).json({ message: 'GitHub App connection not found' });
+  const integration = await Integration.findOne({ _id: integrationId, type: 'github-app' }).lean();
+  if (!integration) return res.status(404).json({ message: 'GitHub App connection not found' });
+  const owner = String(req.body?.owner || integration.config?.owner || '');
+  const repo = String(req.body?.repo || integration.config?.repo || '');
+  if (!/^[A-Za-z0-9_.-]{1,100}$/.test(owner) || !/^[A-Za-z0-9_.-]{1,100}$/.test(repo)) return res.status(400).json({ message: 'Valid owner and repo required' });
+  await GithubGigBinding.deleteOne({ installationId: String(integration.installationId), owner, repo });
+  return res.status(204).json({});
+});
+
 router.post('/ingest', ingestAuth, async (req: AuthReq, res: Res) => {
   try {
     const { provider, integrationId, event, messages } = (req.body || {}) as { provider?: string; integrationId?: string; event?: unknown; messages?: unknown[] };