Cs 10217 trigger command on webhook event by richardhjtan · Pull Request #4074 · cardstack/boxel

richardhjtan · 2026-02-26T14:17:43Z

Use command runner from headless chrome to run command when filter is matched
Introduce github event card def, this can be use as data source for submission card to query the events of a PR
Introduce process github event command to create github event card

…-10217-trigger-command-on-webhook-event

when running github event command experience timeout and file list is not updating in submission realm

richardhjtan · 2026-02-26T14:24:32Z

packages/host/app/commands/save-card.ts

-      realm: input.realm,
-      localDir: input.localDir,
-    });
+    if (input.doNotWaitForPersist) {


Added doNotWaitForPersist option for save card command, this avoid timeout issue when running the command in headless chrome

github-actions · 2026-02-26T14:26:35Z

Preview deployments

richardhjtan · 2026-02-26T14:33:58Z

packages/runtime-common/db-queries/session-room-queries.ts

+    "    AND username = '*'",
+    '    AND read = true',
+    '  )',
+    ')',


This is to fix the issue for the user with read-only access (*) to the public submission realm. Before that, users have to refresh the browser to get the latest file list after the GitHub event card is created from the command runner.

The original query only matched rows where a user had an explicit permission entry. It never matched the wildcard username = * row, so users whose only access to a realm comes from a world-readable permission (* read = true) were silently excluded.

The submissions realm only has explicit entries for the realm owner and the submission bot — everyone else accesses it via *. So the realm server never sent Matrix events to their session rooms after a write, and the UI never received the incremental index notification needed to refresh the card list.

Hello @lukemelia @IanCal, does this fix sound reasonable to you?

github-actions · 2026-02-26T15:01:35Z

Host Test Results

1 files ±0 1 suites ±0 1h 33m 46s ⏱️ - 2m 43s
1 871 tests ±0 1 854 ✅ - 1 15 💤 ±0 0 ❌ ±0 2 🔥 +1
1 886 runs ±0 1 867 ✅ - 2 15 💤 ±0 2 ❌ +1 2 🔥 +1

For more details on these errors, see this check.

Results for commit d08e7f7. ± Comparison against base commit 36bd710.

♻️ This comment has been updated with latest results.

…-10217-trigger-command-on-webhook-event

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d08e7f78c8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-02-26T15:26:31Z

packages/host/app/commands/bot-requests/create-listing-pr-request.ts

+      await this.realmServer.createWebhookCommand({
+        incomingWebhookId: githubWebhook.id,
+        command: `${catalogRealmURL}commands/process-github-event/default`,
+        filter: {
+          submissionRealmUrl: this.realmServer.submissionRealmURL,


Prevent duplicate webhook command registrations

Every CreateListingPRRequestCommand run calls registerPRWebhook(), and this code unconditionally POSTs a new webhook command without checking whether the same (incomingWebhookId, command, filter) already exists. Because webhook_commands has no uniqueness guard, repeated PR requests in the same environment will accumulate duplicate registrations, and each incoming GitHub event will enqueue the same command multiple times, causing duplicate event cards and unnecessary queue load.

Useful? React with 👍 / 👎.

I was wondering the same thing. Isn't this done by matrix/scripts/register-github-webhook.ts?

chatgpt-codex-connector · 2026-02-26T15:26:31Z

packages/host/app/commands/save-card.ts

+      this.store.add(input.card, {
+        realm: input.realm,
+        localDir: input.localDir,
+        doNotWaitForPersist: true,


Await save-card add call in non-blocking persist mode

This branch drops the this.store.add(...) promise entirely when doNotWaitForPersist is set. doNotWaitForPersist already makes persistence fire-and-forget inside StoreService.add, but add still performs async setup/validation and can reject before persistence is queued. Not awaiting here can report command success even when save setup fails and can surface unhandled promise rejections under webhook load.

Useful? React with 👍 / 👎.

I also wonder this

Copilot

Pull request overview

This pull request implements webhook command execution functionality to automatically run commands when GitHub webhook events are received. It introduces a GitHub event card definition for storing webhook event data, adds a command to process GitHub events, and includes comprehensive test coverage for the new functionality.

Changes:

Add webhook command execution with filtering support (event type, PR number)
Introduce GitHub event card for storing webhook events as data
Update session room queries to support world-readable realms
Add webhook management methods to realm server service

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`packages/realm-server/handlers/handle-webhook-receiver.ts`	Implements command execution logic with event filtering and queuing
`packages/runtime-common/db-queries/session-room-queries.ts`	Modifies query to include users with world-readable realm access
`packages/realm-server/tests/server-endpoints/webhook-receiver-test.ts`	Adds comprehensive tests for webhook command execution and filtering
`packages/matrix/scripts/register-github-webhook.ts`	New script for registering GitHub webhooks with event filtering
`packages/host/app/services/realm-server.ts`	Adds webhook management API methods (list, create)
`packages/host/app/commands/save-card.ts`	Adds support for non-blocking card persistence
`packages/host/app/commands/bot-requests/create-listing-pr-request.ts`	Integrates webhook registration into PR creation flow
`packages/catalog-realm/github-event/github-event.gts`	New card definition for storing GitHub webhook events
`packages/catalog-realm/commands/process-github-event.gts`	New command to process GitHub webhook events and create event cards
`packages/base/commands/search-card-result.gts`	Adds queryableValue implementation for JsonField
`packages/base/command.gts`	Adds doNotWaitForPersist field to SaveCardInput
`packages/host/app/commands/create-listing-pr.ts`	Minor comment update

Comments suppressed due to low confidence (2)

packages/realm-server/handlers/handle-webhook-receiver.ts:166

Inconsistent logging approach: The code uses console.warn and console.error directly, while other handlers in the codebase use the logger utility from @cardstack/runtime-common. For consistency and better log management (including proper log levels and module identification), consider using the logger utility: const log = logger('webhook-receiver'); and then log.warn(...) and log.error(...).

      console.warn('Failed to parse webhook payload for filtering');
    }

    let eventType = ctxt.req.headers['x-github-event'] as string | undefined;

    let executedCommands = 0;
    for (let commandRow of commandRows) {
      let commandFilter = commandRow.command_filter as Record<
        string,
        any
      > | null;

      // Apply filter if specified
      if (commandFilter) {
        // Check if event type matches filter
        if (commandFilter.eventType && commandFilter.eventType !== eventType) {
          continue;
        }

        // Check if PR number matches filter (for pull_request events)
        if (
          commandFilter.prNumber &&
          payload.pull_request?.number !== commandFilter.prNumber
        ) {
          continue;
        }

        // Additional filter checks can be added here as needed
      }

      let commandURL = commandRow.command as string;
      let submissionRealmUrl =
        (commandFilter?.submissionRealmUrl as string | undefined) ??
        new URL('/submissions/', commandURL).href;

      // Run as the realm owner so they have write permissions in the submission realm
      let realmOwnerRows = await query(dbAdapter, [
        `SELECT username FROM realm_user_permissions WHERE realm_url = `,
        param(submissionRealmUrl),
        ` AND realm_owner = true LIMIT 1`,
      ]);
      let runAs =
        (realmOwnerRows[0]?.username as string | undefined) ??
        (webhook.username as string);

      let commandInput = {
        eventType: eventType ?? '',
        submissionRealmUrl,
        payload,
      };

      try {
        await enqueueRunCommandJob(
          {
            realmURL: submissionRealmUrl,
            realmUsername: runAs,
            runAs,
            command: commandURL,
            commandInput,
          },
          queue,
          dbAdapter,
          userInitiatedPriority,
        );
        executedCommands++;
      } catch (error) {
        console.error(
          `Failed to enqueue webhook command ${commandURL}:`,
          error,
        );

packages/matrix/scripts/register-github-webhook.ts:20

Header name case mismatch: The script uses lowercase 'x-hub-signature-256' in the webhook configuration, but the tests use 'X-Hub-Signature-256' with proper capitalization. While the handler correctly normalizes headers to lowercase when reading (line 213), this inconsistency could cause confusion. Consider using the canonical capitalization 'X-Hub-Signature-256' consistently in both places, as this is the standard format used by GitHub webhooks.

    header: 'x-hub-signature-256',

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-26T18:11:36Z

packages/host/app/commands/bot-requests/create-listing-pr-request.ts

+import type MatrixService from '../services/matrix-service';
+import type RealmServerService from '../services/realm-server';
+import type StoreService from '../services/store';


The import paths for services are incorrect. Since this file is in the bot-requests subdirectory, the imports should use '../../services/' instead of '../services/'. The correct paths should be:

import type MatrixService from '../../services/matrix-service';

import type RealmServerService from '../../services/realm-server';

import type StoreService from '../../services/store';

This pattern is correctly used in send-bot-trigger-event.ts in the same directory.

Suggested change

import type MatrixService from '../services/matrix-service';

import type RealmServerService from '../services/realm-server';

import type StoreService from '../services/store';

import type MatrixService from '../../services/matrix-service';

import type RealmServerService from '../../services/realm-server';

import type StoreService from '../../services/store';

Copilot · 2026-02-26T18:11:37Z

packages/realm-server/handlers/handle-webhook-receiver.ts

+      let realmOwnerRows = await query(dbAdapter, [
+        `SELECT username FROM realm_user_permissions WHERE realm_url = `,
+        param(submissionRealmUrl),
+        ` AND realm_owner = true LIMIT 1`,
+      ]);
+      let runAs =
+        (realmOwnerRows[0]?.username as string | undefined) ??
+        (webhook.username as string);


The database query to fetch realm owner is not wrapped in a try-catch block, but it's inside a loop that processes webhook commands. If this query fails for any reason (e.g., database connection issues), it will cause the entire webhook request to fail with an unhandled exception, potentially losing valid webhook events. Consider wrapping this query in a try-catch block and logging the error while continuing to process other commands, or handle the error gracefully by skipping this specific command.

Suggested change

let realmOwnerRows = await query(dbAdapter, [

`SELECT username FROM realm_user_permissions WHERE realm_url = `,

param(submissionRealmUrl),

` AND realm_owner = true LIMIT 1`,

]);

let runAs =

(realmOwnerRows[0]?.username as string | undefined) ??

(webhook.username as string);

let runAs = webhook.username as string;

try {

let realmOwnerRows = await query(dbAdapter, [

`SELECT username FROM realm_user_permissions WHERE realm_url = `,

param(submissionRealmUrl),

` AND realm_owner = true LIMIT 1`,

]);

if (realmOwnerRows[0]?.username) {

runAs = realmOwnerRows[0].username as string;

}

} catch (error) {

console.error(

`Failed to fetch realm owner for submission realm ${submissionRealmUrl}:`,

error,

);

}

Copilot · 2026-02-26T18:11:37Z

packages/runtime-common/db-queries/session-room-queries.ts

+    'WHERE u.session_room_id IS NOT NULL',
+    'AND (',
+    '  EXISTS (',
+    '    SELECT 1 FROM realm_user_permissions',
+    '    WHERE realm_url =',
    param(realmURL),
-    'AND (rup.read = true OR rup.write = true)',
-    'AND u.session_room_id IS NOT NULL',
+    '    AND username = u.matrix_user_id',
+    '    AND (read = true OR write = true)',
+    '  )',
+    '  OR EXISTS (',
+    '    SELECT 1 FROM realm_user_permissions',
+    '    WHERE realm_url =',
+    param(realmURL),
+    "    AND username = '*'",
+    '    AND read = true',
+    '  )',
+    ')',


The refactored query logic appears to have a potential issue. When a realm is world-readable (username = '*' with read = true), the query will return ALL users with session rooms, not just those who should have access to this specific realm. The OR EXISTS clause for world-readable realms doesn't restrict which users are returned - it just checks if such a permission exists for the realm, and if it does, all users in the WHERE clause match.

This could expose session room information for users who shouldn't have access to this realm. The original JOIN-based approach correctly filtered users to only those with explicit permissions for this realm. Consider revising the logic to ensure that world-readable access doesn't inadvertently expose all user session rooms.

Copilot · 2026-02-26T18:11:38Z

packages/host/app/commands/bot-requests/create-listing-pr-request.ts

+      await this.realmServer.createWebhookCommand({
+        incomingWebhookId: githubWebhook.id,
+        command: `${catalogRealmURL}commands/process-github-event/default`,
+        filter: {
+          submissionRealmUrl: this.realmServer.submissionRealmURL,
+        },
+      });


The registerPRWebhook method creates a new webhook command every time a PR request is made, without checking if an equivalent command already exists. This could lead to duplicate webhook commands being created, which would cause the same webhook event to trigger multiple command executions. Consider adding logic to check if a webhook command with the same filter already exists before creating a new one, similar to the idempotent approach used in the register-github-webhook.ts script (see ensureWebhookCommand function at line 162).

lukemelia

This needs some work. See comments.

lukemelia · 2026-02-26T20:23:47Z

packages/base/command.gts

  @field card = linksTo(CardDef);
  @field realm = contains(StringField);
  @field localDir = contains(StringField);
+  @field doNotWaitForPersist = contains(BooleanField);


Why are we doing this? It seems problematic -- i.e. what if saving fails?

lukemelia · 2026-02-26T20:26:57Z

packages/host/app/commands/bot-requests/create-listing-pr-request.ts

+      const githubWebhook = webhooks.find(
+        (w: { verificationType: string }) =>
+          w.verificationType === 'HMAC_SHA256_HEADER',
+      );


This is not a robust way to lookup the webhook. Other webhooks could use this verification type as well couldn't they?

Probably should go ahead and do the above TODO now

lukemelia · 2026-02-26T20:30:00Z

packages/host/app/services/realm-server.ts

+  get submissionRealmURL(): string {
+    return `${this.url.href}submissions/`;
+  }


This seems awkwardly specific for the realm-server service. Can we define it somewhere else?

lukemelia · 2026-02-26T20:30:27Z

packages/base/commands/search-card-result.gts

+  static [queryableValue](_value: any, _stack: BaseDef[]): null {
+    return null;
+  }


why was this necessary?

lukemelia · 2026-02-26T20:31:05Z

packages/catalog-realm/github-event/github-event.gts

+  @field action = contains(StringField); // 'opened', 'completed', etc.
+  @field prNumber = contains(NumberField);
+  @field prUrl = contains(StringField);
+  @field payload = contains(JsonField); // full raw payload


If you are going to store the full payload, should we just make the other fields computed on it?

lukemelia · 2026-02-26T20:35:14Z

packages/host/app/commands/save-card.ts

+      this.store.add(input.card, {
+        realm: input.realm,
+        localDir: input.localDir,
+        doNotWaitForPersist: true,


I also wonder this

lukemelia · 2026-02-26T20:39:25Z

packages/realm-server/handlers/handle-webhook-receiver.ts

+        if (commandFilter.eventType && commandFilter.eventType !== eventType) {
+          continue;
+        }
+
+        // Check if PR number matches filter (for pull_request events)
+        if (
+          commandFilter.prNumber &&
+          payload.pull_request?.number !== commandFilter.prNumber
+        ) {
+          continue;
+        }
+
+        // Additional filter checks can be added here as needed


The command filter should specify a type along with its configuration and we should use the type to look up a code block somewhere that has this specific logic of comparing the payload with the filter configuration. The logic should not be in line within this handle-webhook-receiver.

lukemelia · 2026-02-26T20:41:13Z

packages/realm-server/handlers/handle-webhook-receiver.ts

+      let submissionRealmUrl =
+        (commandFilter?.submissionRealmUrl as string | undefined) ??
+        new URL('/submissions/', commandURL).href;
+
+      // Run as the realm owner so they have write permissions in the submission realm
+      let realmOwnerRows = await query(dbAdapter, [
+        `SELECT username FROM realm_user_permissions WHERE realm_url = `,
+        param(submissionRealmUrl),
+        ` AND realm_owner = true LIMIT 1`,
+      ]);
+      let runAs =
+        (realmOwnerRows[0]?.username as string | undefined) ??
+        (webhook.username as string);
+
+      let commandInput = {
+        eventType: eventType ?? '',
+        submissionRealmUrl,
+        payload,
+      };


This logic of assembling the command input also should not be in line here. It needs to be abstracted in some way. The idea is that this route handler should handle any webhook in the system, not just the github webhook.

lukemelia · 2026-02-26T20:41:45Z

packages/realm-server/handlers/handle-webhook-receiver.ts

+      try {
+        await enqueueRunCommandJob(
+          {
+            realmURL: submissionRealmUrl,


This shouldn't be fixed. It should be based on something from the database.

lukemelia · 2026-02-26T20:43:32Z

packages/runtime-common/db-queries/session-room-queries.ts

@@ -55,12 +57,23 @@ export async function fetchRealmSessionRooms(
  let rows = await query(dbAdapter, [
    'SELECT u.matrix_user_id, u.session_room_id',
    'FROM users u',
-    'JOIN realm_user_permissions rup',
-    'ON rup.username = u.matrix_user_id',
-    'WHERE rup.realm_url =',
+    'WHERE u.session_room_id IS NOT NULL',
+    'AND (',
+    '  EXISTS (',
+    '    SELECT 1 FROM realm_user_permissions',
+    '    WHERE realm_url =',
    param(realmURL),
-    'AND (rup.read = true OR rup.write = true)',
-    'AND u.session_room_id IS NOT NULL',
+    '    AND username = u.matrix_user_id',
+    '    AND (read = true OR write = true)',
+    '  )',
+    '  OR EXISTS (',
+    '    SELECT 1 FROM realm_user_permissions',
+    '    WHERE realm_url =',
+    param(realmURL),
+    "    AND username = '*'",
+    '    AND read = true',
+    '  )',
+    ')',


Did you check other consumers of this method to see if there are any unintended consequences of this change?

richardhjtan added 8 commits February 24, 2026 21:23

Register webhook and script in create PR command

acb7522

Merge branch 'CS-10190-register-webhook-in-create-pr-command' into CS…

ea7acfb

…-10217-trigger-command-on-webhook-event

Trigger a command to create webhook event card

5e3e5e7

Clean up register webhook script

c1e3cf9

Merge branch 'CS-10190-register-webhook-in-create-pr-command' into CS…

6136475

…-10217-trigger-command-on-webhook-event

Clean up register webhook script

172fcd6

Merge branch 'CS-10190-register-webhook-in-create-pr-command' into CS…

791321b

…-10217-trigger-command-on-webhook-event

Address headless chrome and file indexing issue

3c6f670

when running github event command experience timeout and file list is not updating in submission realm

richardhjtan commented Feb 26, 2026

View reviewed changes

Fix lint and clean up

94246d2

richardhjtan added 2 commits February 26, 2026 23:04

Fix lint

500702b

Merge branch 'CS-10190-register-webhook-in-create-pr-command' into CS…

d08e7f7

…-10217-trigger-command-on-webhook-event

richardhjtan marked this pull request as ready for review February 26, 2026 15:20

richardhjtan requested review from a team February 26, 2026 15:20

chatgpt-codex-connector bot reviewed Feb 26, 2026

View reviewed changes

habdelra requested a review from Copilot February 26, 2026 18:04

Copilot started reviewing on behalf of habdelra February 26, 2026 18:04 View session

Copilot AI reviewed Feb 26, 2026

View reviewed changes

lukemelia requested changes Feb 26, 2026

View reviewed changes

lucaslyl mentioned this pull request Feb 28, 2026

Add PR card UI with mock data #4087

Open

Conversation

richardhjtan commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Feb 26, 2026

Preview deployments

Uh oh!

richardhjtan Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

richardhjtan Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Host Test Results

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

lukemelia left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

richardhjtan commented Feb 26, 2026 •

edited

Loading

richardhjtan Feb 26, 2026 •

edited

Loading

richardhjtan Feb 26, 2026 •

edited

Loading

github-actions bot commented Feb 26, 2026 •

edited

Loading