feat: add bidirectionalLabelMatch option and deprecate exactMatch

Introduce a new bidirectionalLabelMatch option that performs strict
two-way label matching (runner labels must equal workflow labels as a
set). This preserves the existing exactMatch behavior (unidirectional
subset check) to avoid breaking changes.

- Add bidirectionalLabelMatch to MatcherConfig interface (optional)
- Update canRunJob to support bidirectional matching when enabled
- Deprecate exactMatch in Terraform variables with migration guidance
- Add bidirectionalLabelMatch to multi-runner and webhook variable types
- Add new root variable enable_runner_bidirectional_label_match
- Add comprehensive test coverage for bidirectional matching

Author: Brend-Smits

lambdas/functions/webhook/src/runners/dispatch.test.ts

@@ -190,10 +190,10 @@ describe('Dispatcher', () => {
       expect(canRunJob(workflowLabels, runnerLabels, true)).toBe(true);
     });
 
-    it('should NOT accept job with exact match when runner has extra labels.', () => {
+    it('should accept job with an exact match and runner supports requested capabilities.', () => {
       const workflowLabels = ['self-hosted', 'linux', 'x64'];
       const runnerLabels = [['self-hosted', 'linux', 'x64', 'ubuntu-latest']];
-      expect(canRunJob(workflowLabels, runnerLabels, true)).toBe(false);
+      expect(canRunJob(workflowLabels, runnerLabels, true)).toBe(true);
     });
 
     it('should NOT accept job with an exact match and runner not matching requested capabilities.', () => {
@@ -226,10 +226,10 @@ describe('Dispatcher', () => {
       expect(canRunJob(workflowLabels, runnerLabels, false)).toBe(true);
     });
 
-    it('should NOT match when runner has more labels than workflow requests (exactMatch=true).', () => {
+    it('should match when runner has more labels than workflow requests with exactMatch=true (unidirectional).', () => {
       const workflowLabels = ['self-hosted', 'linux', 'x64', 'staging', 'ubuntu-2404'];
       const runnerLabels = [['self-hosted', 'linux', 'x64', 'staging', 'ubuntu-2404', 'on-demand']];
-      expect(canRunJob(workflowLabels, runnerLabels, true)).toBe(false);
+      expect(canRunJob(workflowLabels, runnerLabels, true)).toBe(true);
     });
 
     it('should match when labels are exactly identical with exactMatch=true.', () => {
@@ -255,6 +255,56 @@ describe('Dispatcher', () => {
       const runnerLabels = [['self-hosted', 'gpu']];
       expect(canRunJob(workflowLabels, runnerLabels, false)).toBe(true);
     });
+
+    // bidirectionalLabelMatch tests
+    it('should NOT match when runner has more labels than workflow requests (bidirectionalLabelMatch=true).', () => {
+      const workflowLabels = ['self-hosted', 'linux', 'x64', 'staging', 'ubuntu-2404'];
+      const runnerLabels = [['self-hosted', 'linux', 'x64', 'staging', 'ubuntu-2404', 'on-demand']];
+      expect(canRunJob(workflowLabels, runnerLabels, false, true)).toBe(false);
+    });
+
+    it('should NOT match when workflow has more labels than runner (bidirectionalLabelMatch=true).', () => {
+      const workflowLabels = ['self-hosted', 'linux', 'x64', 'ubuntu-latest', 'gpu'];
+      const runnerLabels = [['self-hosted', 'linux', 'x64']];
+      expect(canRunJob(workflowLabels, runnerLabels, false, true)).toBe(false);
+    });
+
+    it('should match when labels are exactly identical with bidirectionalLabelMatch=true.', () => {
+      const workflowLabels = ['self-hosted', 'linux', 'on-demand'];
+      const runnerLabels = [['self-hosted', 'linux', 'on-demand']];
+      expect(canRunJob(workflowLabels, runnerLabels, false, true)).toBe(true);
+    });
+
+    it('should match with bidirectionalLabelMatch=true when labels are in different order.', () => {
+      const workflowLabels = ['linux', 'self-hosted', 'x64'];
+      const runnerLabels = [['self-hosted', 'linux', 'x64']];
+      expect(canRunJob(workflowLabels, runnerLabels, false, true)).toBe(true);
+    });
+
+    it('should match with bidirectionalLabelMatch=true when labels are completely shuffled.', () => {
+      const workflowLabels = ['x64', 'ubuntu-latest', 'self-hosted', 'linux'];
+      const runnerLabels = [['self-hosted', 'linux', 'x64', 'ubuntu-latest']];
+      expect(canRunJob(workflowLabels, runnerLabels, false, true)).toBe(true);
+    });
+
+    it('should match with bidirectionalLabelMatch=true ignoring case.', () => {
+      const workflowLabels = ['Self-Hosted', 'Linux', 'X64'];
+      const runnerLabels = [['self-hosted', 'linux', 'x64']];
+      expect(canRunJob(workflowLabels, runnerLabels, false, true)).toBe(true);
+    });
+
+    it('should NOT match empty workflow labels with bidirectionalLabelMatch=true.', () => {
+      const workflowLabels: string[] = [];
+      const runnerLabels = [['self-hosted', 'linux', 'x64']];
+      expect(canRunJob(workflowLabels, runnerLabels, false, true)).toBe(false);
+    });
+
+    it('bidirectionalLabelMatch takes precedence over exactMatch when both are true.', () => {
+      const workflowLabels = ['self-hosted', 'linux', 'x64'];
+      const runnerLabels = [['self-hosted', 'linux', 'x64', 'ubuntu-latest']];
+      // exactMatch alone would accept this (runner has extra labels), but bidirectional should reject
+      expect(canRunJob(workflowLabels, runnerLabels, true, true)).toBe(false);
+    });
   });
 });
 

lambdas/functions/webhook/src/runners/dispatch.ts

@@ -42,12 +42,21 @@ async function handleWorkflowJob(
       `Job ID: ${body.workflow_job.id}, Job Name: ${body.workflow_job.name}, ` +
       `Run ID: ${body.workflow_job.run_id}, Labels: ${JSON.stringify(body.workflow_job.labels)}`,
   );
-  // sort the queuesConfig by order of matcher config exact match, with all true matches lined up ahead.
+  // sort the queuesConfig by order of matcher config exact/bidirectional match, with all true matches lined up ahead.
   matcherConfig.sort((a, b) => {
-    return a.matcherConfig.exactMatch === b.matcherConfig.exactMatch ? 0 : a.matcherConfig.exactMatch ? -1 : 1;
+    const aStrict = a.matcherConfig.bidirectionalLabelMatch || a.matcherConfig.exactMatch;
+    const bStrict = b.matcherConfig.bidirectionalLabelMatch || b.matcherConfig.exactMatch;
+    return aStrict === bStrict ? 0 : aStrict ? -1 : 1;
   });
   for (const queue of matcherConfig) {
-    if (canRunJob(body.workflow_job.labels, queue.matcherConfig.labelMatchers, queue.matcherConfig.exactMatch)) {
+    if (
+      canRunJob(
+        body.workflow_job.labels,
+        queue.matcherConfig.labelMatchers,
+        queue.matcherConfig.exactMatch,
+        queue.matcherConfig.bidirectionalLabelMatch,
+      )
+    ) {
       await sendActionRequest({
         id: body.workflow_job.id,
         repositoryName: body.repository.name,
@@ -80,21 +89,22 @@ export function canRunJob(
   workflowJobLabels: string[],
   runnerLabelsMatchers: string[][],
   workflowLabelCheckAll: boolean,
+  bidirectionalLabelMatch = false,
 ): boolean {
   runnerLabelsMatchers = runnerLabelsMatchers.map((runnerLabel) => {
     return runnerLabel.map((label) => label.toLowerCase());
   });
-  const workflowLabelsLower = workflowJobLabels.map((wl) => wl.toLowerCase());
 
   let match: boolean;
-  if (workflowLabelCheckAll) {
+  if (bidirectionalLabelMatch) {
+    const workflowLabelsLower = workflowJobLabels.map((wl) => wl.toLowerCase());
     match = runnerLabelsMatchers.some(
       (rl) => workflowLabelsLower.every((wl) => rl.includes(wl)) && rl.every((r) => workflowLabelsLower.includes(r)),
     );
   } else {
-    const matchLabels = runnerLabelsMatchers.some((rl) =>
-      workflowJobLabels.some((wl) => rl.includes(wl.toLowerCase())),
-    );
+    const matchLabels = workflowLabelCheckAll
+      ? runnerLabelsMatchers.some((rl) => workflowJobLabels.every((wl) => rl.includes(wl.toLowerCase())))
+      : runnerLabelsMatchers.some((rl) => workflowJobLabels.some((wl) => rl.includes(wl.toLowerCase())));
     match = workflowJobLabels.length === 0 ? !matchLabels : matchLabels;
   }
 

lambdas/functions/webhook/src/sqs/index.ts

@@ -17,6 +17,7 @@ export interface ActionRequestMessage {
 export interface MatcherConfig {
   labelMatchers: string[][];
   exactMatch: boolean;
+  bidirectionalLabelMatch?: boolean;
 }
 
 export type RunnerConfig = RunnerMatcherConfig[];

main.tf

@@ -114,6 +114,7 @@ module "webhook" {
       matcherConfig : {
         labelMatchers : [local.runner_labels]
         exactMatch : var.enable_runner_workflow_job_labels_check_all
+        bidirectionalLabelMatch : var.enable_runner_bidirectional_label_match
       }
     }
   }

modules/multi-runner/variables.tf

@@ -181,9 +181,10 @@ variable "multi_runner_config" {
       }), {})
     })
     matcherConfig = object({
-      labelMatchers = list(list(string))
-      exactMatch    = optional(bool, false)
-      priority      = optional(number, 999)
+      labelMatchers            = list(list(string))
+      exactMatch               = optional(bool, false)
+      bidirectionalLabelMatch  = optional(bool, false)
+      priority                 = optional(number, 999)
     })
     redrive_build_queue = optional(object({
       enabled         = bool
@@ -252,7 +253,8 @@ variable "multi_runner_config" {
       }
       matcherConfig: {
         labelMatchers: "The list of list of labels supported by the runner configuration. `[[self-hosted, linux, x64, example]]`"
-        exactMatch: "If set to true all labels in the workflow job must match the GitHub labels (os, architecture and `self-hosted`). When false if __any__ workflow label matches it will trigger the webhook."
+        exactMatch: "DEPRECATED: Use `bidirectionalLabelMatch` instead. If set to true all labels in the workflow job must match the GitHub labels (os, architecture and `self-hosted`). When false if __any__ workflow label matches it will trigger the webhook. Note: this only checks that workflow labels are a subset of runner labels, not the reverse."
+        bidirectionalLabelMatch: "If set to true, the runner labels and workflow job labels must be an exact two-way match (same set, any order, no extras or missing labels). This is stricter than `exactMatch` which only checks that workflow labels are a subset of runner labels. When false, if __any__ workflow label matches it will trigger the webhook."
         priority: "If set it defines the priority of the matcher, the matcher with the lowest priority will be evaluated first. Default is 999, allowed values 0-999."
       }
       redrive_build_queue: "Set options to attach (optional) a dead letter queue to the build queue, the queue between the webhook and the scale up lambda. You have the following options. 1. Disable by setting `enabled` to false. 2. Enable by setting `enabled` to `true`, `maxReceiveCount` to a number of max retries."

modules/webhook/variables.tf

@@ -28,9 +28,10 @@ variable "runner_matcher_config" {
     arn = string
     id  = string
     matcherConfig = object({
-      labelMatchers = list(list(string))
-      exactMatch    = bool
-      priority      = optional(number, 999)
+      labelMatchers            = list(list(string))
+      exactMatch               = bool
+      bidirectionalLabelMatch  = optional(bool, false)
+      priority                 = optional(number, 999)
     })
   }))
   validation {

variables.tf

@@ -624,11 +624,17 @@ variable "log_level" {
 }
 
 variable "enable_runner_workflow_job_labels_check_all" {
-  description = "If set to true all labels in the workflow job must match the GitHub labels (os, architecture and `self-hosted`). When false if __any__ label matches it will trigger the webhook."
+  description = "DEPRECATED: Use `enable_runner_bidirectional_label_match` instead. If set to true all labels in the workflow job must match the GitHub labels (os, architecture and `self-hosted`). When false if __any__ label matches it will trigger the webhook. Note: this only checks that workflow labels are a subset of runner labels, not the reverse."
   type        = bool
   default     = true
 }
 
+variable "enable_runner_bidirectional_label_match" {
+  description = "If set to true, the runner labels and workflow job labels must be an exact two-way match (same set, any order, no extras or missing labels). This is stricter than `enable_runner_workflow_job_labels_check_all` which only checks that workflow labels are a subset of runner labels. When false, if __any__ label matches it will trigger the webhook."
+  type        = bool
+  default     = false
+}
+
 variable "matcher_config_parameter_store_tier" {
   description = "The tier of the parameter store for the matcher configuration. Valid values are `Standard`, and `Advanced`."
   type        = string