feat(notifications): preview-deploy screenshot pipeline (provider-agnostic)

[isadeks]

Closes #240.

Summary

• New deploy-preview screenshot pipeline. Listens for GitHub deployment_status: success events from any provider (Vercel, Amplify Hosting, Netlify, GitHub Actions custom CD); captures the preview URL via AgentCore Browser; posts a markdown image comment on the open PR.
• Optional Linear-side comment: if a Linear identifier is in the PR title/body and Linear is configured (per feat(linear): OAuth migration with per-workspace token storage (Phase 2.0b) #160), the same screenshot lands on the Linear issue.
• New bgagent github CLI subcommand: webhook-info + set-webhook-secret.
• Provider-agnostic. The repo's worked example uses Vercel because that's what was smoke-tested.

Architecture

• Lambda-only post-PR (no LLM). Receiver verifies HMAC, dedupes, async-invokes processor.
• AgentCore Browser via SigV4-presigned WSS + Chrome DevTools Protocol — no Playwright in the bundle.
• Private S3 + CloudFront with Origin Access Control. Bucket fully private; CloudFront serves images anonymously over HTTPS so GitHub markdown image embeds render without auth.
• WAF exemption on /v1/github/webhook for GenericRFI_BODY (deployment_status payloads embed absolute URLs).

Test plan

• Full CDK suite green locally: 1810 tests, 101 suites passing
• Smoke-tested end-to-end on dev stack: Vercel-connected repo → push commit → preview builds → screenshot lands on PR ~12s after Vercel reports success → also lands on linked Linear issue
• Provider-agnostic verified: no Vercel-specific code paths, only deployment_status filtering by configurable SCREENSHOT_TARGET_ENVIRONMENT (default Preview)
• CI: build + tests pass on PR

Out of scope (followups)

• IAM scoping — currently bedrock-agentcore:* for the processor; tighter action set is followup.
• Tests for the screenshot pipeline (mock for AgentCore Browser WSS, GitHub PR-lookup, S3, comment posting).
• Deploy-protection bypass tokens for providers that gate previews behind auth.
• Multi-workspace Linear lookup prefix-routing.

[krokoko]

Review — Preview-deploy screenshot pipeline

Thanks for this — it's a really well-built feature. The receiver/processor topology faithfully mirrors LinearIntegration, the verify module follows linear-verify.ts, the private-S3 + CloudFront-OAC design is the correct answer to account-level Block Public Access, and the SigV4-presigned-WSS handshake is nicely reasoned (the commit trail documenting why you landed there is genuinely helpful). The docs are thorough and the Starlight mirrors are regenerated and committed. A few things I'd like to see addressed before merge, then some non-blocking notes.

Requesting changes on

1. Tests on the new security boundary. POST /v1/github/webhook is authorizationType: NONE, so the in-Lambda HMAC is the entire authentication path — and it currently ships with no unit tests. The repo already has copy-pasteable templates for exactly this shape (slack-verify.test.ts, linear-webhook.test.ts). The load-bearing branches I'd want pinned:

• verifyGitHubSignature — the timingSafeEqual unequal-length throw guard, the sha256= prefix check, and the rotation re-fetch in verifyGitHubRequest.
• github-webhook.ts receiver — state/environment filter gates, and the dedup ConditionalCheckFailedException + rollback-DeleteCommand path.
• extractLinearIdentifier — pure function, trivial to test, and the g-flag lastIndex reset is the kind of thing that breaks silently on back-to-back calls.

The browser/CDP plumbing in agentcore-browser.ts is a fair followup (it's smoke-tested), but the HMAC + receiver routing + regex are ~2–3h with the existing templates. Worth noting the coverage gate added in b277cc6 may reject this as-is.

2. Unrelated default-label change (bgagent → abca). linear-webhook-processor.ts:34 flips DEFAULT_LABEL_FILTER, but cli/src/commands/linear.ts:50, the mapping-table doc, and LINEAR_SETUP_GUIDE.md:89 ("Default trigger label is bgagent") still say bgagent. Any onboarded project whose row lacks an explicit label_filter would silently switch trigger label on deploy. Could we either split this out of the screenshot PR, or align all four sites and add a migration note? (The label-gate reorder itself looks correct and the two new regression tests are great — it's just the default-value change + drift.)

3. Processor failures are invisible. WebhookProcessorFn is invoked InvocationType: 'Event' with no DLQ / onFailure / Errors alarm, and every failure path logs-and-returns. Since the receiver already 200'd, GitHub won't redeliver — so a systemic break (IAM, AgentCore quota, token rotation) stops 100% of screenshots with no signal anywhere. Could we add an SQS DLQ + a CloudWatch alarm on processor Errors?

Non-blocking suggestions

• WAF rationale vs. code. /v1/github/webhook is added to the priority-1 scope-down, which excludes only SizeRestrictions_BODY — so GenericRFI_BODY is still evaluated on the path, which doesn't match the commit message ("trips GenericRFI_BODY"). Since the smoke test passed, the real blocker may have been body-size rather than RFI. Worth reconciling the comment/commit with what's exempted (and the troubleshooting doc, which tells operators the path is RFI-exempt).
• Error/login-page screenshots. Page.navigate only checks errorText; an HTTP 4xx/5xx or auth wall navigates "successfully" and the 404/login PNG gets posted as if it were the app (the guide acknowledges this). Enabling the Network domain and skipping the post when the main-document status isn't 2xx would avoid posting confidently-wrong output.
• WebSocket leak on open-timeout (agentcore-browser.ts:1469-1494): the open promise rejects without ws.close()/terminate(), and the throw escapes before the try/finally, leaving a dangling socket per failed attempt. Wrapping the open in the same finally would tidy this up.
• Unguarded res.json() (github-webhook-processor.ts:854): a 2xx non-array/HTML body throws, and since findPullRequestForShaWithRetry has no try/catch, it crashes the (un-DLQ'd) processor. An Array.isArray guard returning null keeps the function's existing contract.
• SSRF note: environment_url flows from the payload straight into Page.navigate. It's HMAC-gated and runs in the managed AgentCore session (not the Lambda VPC), so blast radius is bounded — but a scheme/host allowlist before navigating would be a cheap hardening follow-up.
• bedrock-agentcore:* on * is broader than the project precedent (task-orchestrator.ts scopes specific actions). Acknowledged in the guide as a known gap — worth a tracked follow-up issue.
• Stale strings: a couple of CfnOutput descriptions still say "Vercel-preview", and the construct doc-comment still calls it a "Public-read screenshot S3 bucket" though it's now private + OAC.

Really nice work overall — the bulk of this is the test coverage on the auth boundary and making failures observable; the rest is polish. Happy to pair on the test scaffolding if useful.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 99.81061% with 1 line in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@e3abe92). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
...dk/src/constructs/github-screenshot-integration.ts	99.62%	1 Missing ⚠️
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #241   +/-   ##
=======================================
  Coverage        ?   86.15%           
=======================================
  Files           ?      169           
  Lines           ?    40038           
  Branches        ?     3931           
=======================================
  Hits            ?    34495           
  Misses          ?     5543           
  Partials        ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.