feat: Add workflow job support (#6)

* feat: Add workflow job support

* Add changeset

Author: julio-rocketchat

.changeset/dull-boats-go.md

@@ -0,0 +1,5 @@
+---
+"layne": minor
+---
+
+Adds support for workflow jobs alongside workflow runs

docs/configuration.md

@@ -291,17 +291,46 @@ If neither `$global` nor the repo defines a `labels` key, the feature is a no-op
 
 ## Trigger
 
-By default Layne scans every pull request immediately when it is opened, synchronised, or reopened. The `trigger` block lets you defer scanning until a specific CI workflow completes — useful for open-source repositories where workflows from external contributors require maintainer approval before they run.
+By default Layne scans every pull request immediately when it is opened, synchronised, or reopened (`pull_request` trigger). This is the right choice for private or internal repositories where all contributors are trusted and every PR is worth scanning.
+
+For public repositories, two problems arise:
+
+**1. GitHub workflow approval gates.** GitHub requires maintainer approval before running Actions workflows for first-time external contributors. This means Layne's `pull_request` event fires and the scan starts running — spawning Semgrep processes, Trufflehog processes, and Anthropic API calls — on code that may never actually execute in CI because a maintainer hasn't approved it yet. You end up scanning throwaway spam PRs, bot noise, and low-effort contributions that will be closed without review.
+
+**2. Wasted spend on failing code.** Even for trusted contributors, a PR that immediately breaks CI is unlikely to be merged. Scanning it early means burning Semgrep CPU time, Trufflehog I/O, and — most importantly — Anthropic API credits on code that will need to be revised anyway. If CI runs for 5 minutes and fails on a type error, the security scan result is moot.
+
+The `workflow_run` and `workflow_job` triggers solve both problems by deferring the scan until after CI has already run. You only scan code that cleared your quality gate, which is almost always the only code that will ever land in your main branch.
+
+### Cost impact
+
+The Claude adapter makes Anthropic API calls charged per token. On a busy public repository, the difference between scanning every PR immediately and scanning only after CI passes can be significant:
+
+- Repositories with high external contributor volume often receive many low-quality PRs (spam, trivial fixes, automated dependency bumps that fail tests). These will never merge and don't need security scanning.
+- PRs that fail CI within the first few minutes consume scan compute for a result no one will act on. A 30-second CI failure gate that rejects 40% of PRs saves 40% of scan costs immediately.
+- Semgrep and Trufflehog are cheap (CPU only), but the Claude adapter is billed per token at Anthropic API rates. On a repo with many PRs per day, this adds up quickly. Deferring to after CI passes is the single most effective cost control available.
+
+The deferred triggers do not reduce security coverage for PRs that pass CI — the scan still runs on every commit that clears the gate, before merge.
+
+### Choosing between `workflow_run` and `workflow_job`
+
+| | `workflow_run` | `workflow_job` |
+|---|---|---|
+| Gates on | An entire workflow completing | A single named job completing |
+| Use when | You want CI fully done before scanning | You have a fast early gate (e.g. lint, approval job) and want to scan sooner |
+| Latency | Scan starts after the longest job in the workflow | Scan starts as soon as the named job finishes |
+| Typical setup | One CI workflow, wait for all of it | A dedicated `security-gate` job that runs approval checks early |
 
 ### Modes
 
 | `on` | Behaviour |
 |---|---|
 | `pull_request` | *(default)* Scan fires immediately on `opened`, `synchronize`, and `reopened` events |
 | `workflow_run` | Scan fires when the named CI workflow completes with a matching conclusion |
+| `workflow_job` | Scan fires when the named CI job completes with a matching conclusion |
 
 ### Schema
 
+**`workflow_run`:**
 ```json
 {
   "owner/repo": {
@@ -314,24 +343,38 @@ By default Layne scans every pull request immediately when it is opened, synchro
 }
 ```
 
+**`workflow_job`:**
+```json
+{
+  "owner/repo": {
+    "trigger": {
+      "on":          "workflow_job",
+      "job":         "security-gate",
+      "conclusions": ["success"]
+    }
+  }
+}
+```
+
 | Key | Type | Default | Description |
 |---|---|---|---|
-| `on` | `"pull_request"` \| `"workflow_run"` | `"pull_request"` | When to trigger the scan |
+| `on` | `"pull_request"` \| `"workflow_run"` \| `"workflow_job"` | `"pull_request"` | When to trigger the scan |
 | `workflow` | string | — | Name of the GitHub Actions workflow to watch. Required when `on` is `"workflow_run"` |
-| `conclusions` | string[] | `["success"]` | Workflow conclusions that trigger the scan. Valid values: `success`, `failure`, `neutral`, `cancelled`, `skipped`, `timed_out`, `action_required` |
+| `job` | string | — | Name of the GitHub Actions job to watch. Required when `on` is `"workflow_job"` |
+| `conclusions` | string[] | `["success"]` | Conclusions that trigger the scan. Valid values: `success`, `failure`, `neutral`, `cancelled`, `skipped`, `timed_out`, `action_required` |
 
 > **`trigger` can be set globally.** Set it under `$global` to apply to all repos, then override per-repo as needed.
 
-### How `workflow_run` works
+### How deferred triggers work
 
-When `on: workflow_run` is configured for a repo:
+Both `workflow_run` and `workflow_job` follow the same two-stage pattern:
 
 1. **On `pull_request`** — Layne caches the PR metadata in Redis (7-day TTL) and creates a `skipped` Check Run so the deferral is visible in the PR status UI. No scan is enqueued yet.
-2. **On `workflow_run completed`** — When the named workflow finishes with a matching conclusion, Layne looks up the cached PR metadata and enqueues the scan. If the cache is cold (e.g. Layne was offline when the PR was opened), Layne falls back to the GitHub API to find the associated PR.
+2. **On the trigger event completing** — When the named workflow or job finishes with a matching conclusion, Layne looks up the cached PR metadata and enqueues the scan. If the cache is cold (e.g. Layne was offline when the PR was opened), Layne falls back to the GitHub API to find the associated PR.
 
 ### Failure mode
 
-If the watched workflow is renamed or removed, Layne never receives the `workflow_run` event and the scan never runs. To fail **closed** (safe) rather than **open** (silent), make Layne's Check Run a **required status check** in branch protection — then a missing check blocks merging and the absence is immediately visible.
+If the watched workflow or job is renamed or removed, Layne never receives the event and the scan never runs. To fail **closed** (safe) rather than **open** (silent), make Layne's Check Run a **required status check** in branch protection — then a missing check blocks merging and the absence is immediately visible.
 
 ### Examples
 
@@ -347,6 +390,18 @@ If the watched workflow is renamed or removed, Layne never receives the `workflo
 }
 ```
 
+**Scan after a specific job completes (finer-grained than a whole workflow):**
+```json
+{
+  "owner/repo": {
+    "trigger": {
+      "on":  "workflow_job",
+      "job": "security-gate"
+    }
+  }
+}
+```
+
 **Scan regardless of whether CI passes or fails (workflow was approved, code is worth scanning):**
 ```json
 {

src/__tests__/server.test.js

@@ -30,8 +30,9 @@ const { loadScanConfig }                             = await import('../config.j
 const { webhooksTotal }                              = await import('../metrics.js');
 const { app, verifySignature, processWebhookRequest } = await import('../server.js');
 
-const PR_TRIGGER_CONFIG       = { trigger: { on: 'pull_request' } };
-const WORKFLOW_TRIGGER_CONFIG = { trigger: { on: 'workflow_run', workflow: 'Tests Done', conclusions: ['success'] } };
+const PR_TRIGGER_CONFIG          = { trigger: { on: 'pull_request' } };
+const WORKFLOW_TRIGGER_CONFIG    = { trigger: { on: 'workflow_run', workflow: 'Tests Done', conclusions: ['success'] } };
+const WORKFLOW_JOB_TRIGGER_CONFIG = { trigger: { on: 'workflow_job', job: 'security-scan', conclusions: ['success'] } };
 
 function sign(body) {
   return 'sha256=' + crypto
@@ -83,6 +84,29 @@ function workflowRunPayload({
   });
 }
 
+function workflowJobPayload({
+  action   = 'completed',
+  jobName  = 'security-scan',
+  conclusion = 'success',
+  headSha  = 'abc123',
+} = {}) {
+  return JSON.stringify({
+    action,
+    workflow_job: {
+      name:       jobName,
+      conclusion,
+      head_sha:   headSha,
+    },
+    repository: {
+      name:       'my-repo',
+      full_name:  'org/my-repo',
+      clone_url:  'https://github.com/org/my-repo.git',
+      owner:      { login: 'org' },
+    },
+    installation: { id: 987 },
+  });
+}
+
 function webhookRequest(body, { event = 'pull_request', signature } = {}) {
   const bodyStr = typeof body === 'string' ? body : JSON.stringify(body);
   return {
@@ -162,7 +186,7 @@ describe('processWebhookRequest()', () => {
     expect(createCheckRun).not.toHaveBeenCalled();
   });
 
-  it('ignores non-pull_request / non-workflow_run events', async () => {
+  it('ignores events that are not pull_request, workflow_run, or workflow_job', async () => {
     const res = await processWebhookRequest(webhookRequest(JSON.stringify({ action: 'created' }), {
       event: 'push',
     }));
@@ -527,3 +551,218 @@ describe('workflow_run trigger — workflow_run event', () => {
     expect(scanQueue.add).toHaveBeenCalledOnce();
   });
 });
+
+// ---------------------------------------------------------------------------
+// workflow_job trigger — pull_request events deferred
+// ---------------------------------------------------------------------------
+
+describe('workflow_job trigger — pull_request event', () => {
+  beforeEach(() => {
+    loadScanConfig.mockResolvedValue(WORKFLOW_JOB_TRIGGER_CONFIG);
+  });
+
+  it('does not enqueue a scan when the repo uses workflow_job trigger', async () => {
+    const res = await processWebhookRequest(webhookRequest(prPayload('opened')));
+
+    expect(res).toEqual({ status: 200, body: 'Deferred' });
+    expect(scanQueue.add).not.toHaveBeenCalled();
+    expect(createCheckRun).not.toHaveBeenCalled();
+  });
+
+  it('caches PR metadata in Redis with a 7-day TTL', async () => {
+    await processWebhookRequest(webhookRequest(prPayload('opened')));
+
+    expect(redis.set).toHaveBeenCalledWith(
+      'layne:pr:org/my-repo:abc123',
+      expect.any(String),
+      'EX',
+      7 * 24 * 60 * 60
+    );
+
+    const cached = JSON.parse(redis.set.mock.calls[0][1]);
+    expect(cached).toMatchObject({
+      prNumber:       42,
+      headSha:        'abc123',
+      headRef:        'feature/login',
+      baseSha:        'def456',
+      baseRef:        'main',
+      labels:         ['bug'],
+      installationId: 987,
+    });
+  });
+
+  it('creates a skipped check run with the configured job name in the summary', async () => {
+    await processWebhookRequest(webhookRequest(prPayload('opened')));
+
+    expect(skipCheckRun).toHaveBeenCalledWith(expect.objectContaining({
+      installationId: 987,
+      owner:          'org',
+      repo:           'my-repo',
+      headSha:        'abc123',
+      summary:        expect.stringContaining('security-scan'),
+    }));
+  });
+
+  it('still returns Deferred even if skipCheckRun throws', async () => {
+    skipCheckRun.mockRejectedValueOnce(new Error('GitHub API error'));
+
+    const res = await processWebhookRequest(webhookRequest(prPayload('opened')));
+
+    expect(res).toEqual({ status: 200, body: 'Deferred' });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// workflow_job trigger — workflow_job events
+// ---------------------------------------------------------------------------
+
+describe('workflow_job trigger — workflow_job event', () => {
+  const CACHED_PR = JSON.stringify({
+    prNumber:       42,
+    headSha:        'abc123',
+    headRef:        'feature/login',
+    baseSha:        'def456',
+    baseRef:        'main',
+    labels:         ['bug'],
+    installationId: 987,
+    cloneUrl:       'https://github.com/org/my-repo.git',
+    repoFullName:   'org/my-repo',
+  });
+
+  beforeEach(() => {
+    loadScanConfig.mockResolvedValue(WORKFLOW_JOB_TRIGGER_CONFIG);
+    redis.get.mockResolvedValue(CACHED_PR);
+  });
+
+  it('enqueues a scan when the workflow job matches config', async () => {
+    const res = await processWebhookRequest(webhookRequest(workflowJobPayload(), { event: 'workflow_job' }));
+
+    expect(res).toEqual({ status: 200, body: 'Accepted' });
+    expect(createCheckRun).toHaveBeenCalledOnce();
+    expect(scanQueue.add).toHaveBeenCalledOnce();
+  });
+
+  it('enqueues with the correct job payload from the cached PR data', async () => {
+    await processWebhookRequest(webhookRequest(workflowJobPayload(), { event: 'workflow_job' }));
+
+    const [, jobData] = scanQueue.add.mock.calls[0];
+    expect(jobData).toMatchObject({
+      owner:          'org',
+      repo:           'my-repo',
+      headSha:        'abc123',
+      headRef:        'feature/login',
+      baseSha:        'def456',
+      baseRef:        'main',
+      prNumber:       42,
+      labels:         ['bug'],
+      installationId: 987,
+      checkRunId:     99,
+    });
+  });
+
+  it('uses the correct job ID for deduplication', async () => {
+    await processWebhookRequest(webhookRequest(workflowJobPayload(), { event: 'workflow_job' }));
+
+    const [, , opts] = scanQueue.add.mock.calls[0];
+    expect(opts.jobId).toBe('org/my-repo#42@abc123');
+  });
+
+  it('ignores workflow_job events where action is not "completed"', async () => {
+    const res = await processWebhookRequest(webhookRequest(
+      workflowJobPayload({ action: 'in_progress' }), { event: 'workflow_job' }
+    ));
+
+    expect(res).toEqual({ status: 200, body: 'Event ignored' });
+    expect(scanQueue.add).not.toHaveBeenCalled();
+  });
+
+  it('ignores workflow_job events for a different job name', async () => {
+    const res = await processWebhookRequest(webhookRequest(
+      workflowJobPayload({ jobName: 'lint' }), { event: 'workflow_job' }
+    ));
+
+    expect(res).toEqual({ status: 200, body: 'Event ignored' });
+    expect(scanQueue.add).not.toHaveBeenCalled();
+  });
+
+  it('ignores workflow_job events with a non-matching conclusion', async () => {
+    const res = await processWebhookRequest(webhookRequest(
+      workflowJobPayload({ conclusion: 'failure' }), { event: 'workflow_job' }
+    ));
+
+    expect(res).toEqual({ status: 200, body: 'Event ignored' });
+    expect(scanQueue.add).not.toHaveBeenCalled();
+  });
+
+  it('ignores workflow_job events when the repo uses pull_request trigger', async () => {
+    loadScanConfig.mockResolvedValue(PR_TRIGGER_CONFIG);
+
+    const res = await processWebhookRequest(webhookRequest(workflowJobPayload(), { event: 'workflow_job' }));
+
+    expect(res).toEqual({ status: 200, body: 'Event ignored' });
+    expect(scanQueue.add).not.toHaveBeenCalled();
+  });
+
+  it('deduplicates: does not enqueue when the job already exists', async () => {
+    scanQueue.getJob.mockResolvedValueOnce({ id: 'org/my-repo#42@abc123' });
+
+    const res = await processWebhookRequest(webhookRequest(workflowJobPayload(), { event: 'workflow_job' }));
+
+    expect(res).toEqual({ status: 200, body: 'Accepted' });
+    expect(createCheckRun).not.toHaveBeenCalled();
+    expect(scanQueue.add).not.toHaveBeenCalled();
+  });
+
+  it('returns 200 with "PR not found" when cache is cold and GitHub API returns nothing', async () => {
+    redis.get.mockResolvedValue(null);
+    findPullRequestBySha.mockResolvedValue(null);
+
+    const res = await processWebhookRequest(webhookRequest(workflowJobPayload(), { event: 'workflow_job' }));
+
+    expect(res).toEqual({ status: 200, body: 'PR not found' });
+    expect(scanQueue.add).not.toHaveBeenCalled();
+  });
+
+  it('falls back to GitHub API when cache is cold and enqueues from API data', async () => {
+    redis.get.mockResolvedValue(null);
+    findPullRequestBySha.mockResolvedValue({
+      number: 42,
+      head:   { ref: 'feature/login', sha: 'abc123' },
+      base:   { ref: 'main',          sha: 'def456' },
+      labels: [{ name: 'bug' }],
+    });
+
+    const res = await processWebhookRequest(webhookRequest(workflowJobPayload(), { event: 'workflow_job' }));
+
+    expect(res).toEqual({ status: 200, body: 'Accepted' });
+    expect(findPullRequestBySha).toHaveBeenCalledWith(expect.objectContaining({
+      owner:   'org',
+      repo:    'my-repo',
+      headSha: 'abc123',
+    }));
+    expect(scanQueue.add).toHaveBeenCalledOnce();
+  });
+
+  it('returns "PR not found" when cache is cold and GitHub API throws', async () => {
+    redis.get.mockResolvedValue(null);
+    findPullRequestBySha.mockRejectedValue(new Error('API error'));
+
+    const res = await processWebhookRequest(webhookRequest(workflowJobPayload(), { event: 'workflow_job' }));
+
+    expect(res).toEqual({ status: 200, body: 'PR not found' });
+    expect(scanQueue.add).not.toHaveBeenCalled();
+  });
+
+  it('enqueues with configured non-default conclusions', async () => {
+    loadScanConfig.mockResolvedValue({
+      trigger: { on: 'workflow_job', job: 'security-scan', conclusions: ['success', 'failure'] },
+    });
+
+    const res = await processWebhookRequest(webhookRequest(
+      workflowJobPayload({ conclusion: 'failure' }), { event: 'workflow_job' }
+    ));
+
+    expect(res).toEqual({ status: 200, body: 'Accepted' });
+    expect(scanQueue.add).toHaveBeenCalledOnce();
+  });
+});