Plan: Report Issue State by GitHub Webhook¶
Overview¶
Status: Done (WH-1..WH-5; prod-checked 2026-10-21) Date: 2026-10-21 ADR: ADR-0026 D7 · Spec: spec-in-app-report v1.3 (BR-9, BR-10, FR-8, EC-14..EC-17) · Parent plan: plan-in-app-report Size: Small feature on top of In-App Report. 4 implementation tasks (~230 LOC non-test), plus owner setup (WH-5).
Objective¶
GitHub pushes closed / reopened issue events to the app; the app verifies the HMAC signature and stores the state and its reason on app_report. The report list uses the stored state and calls GitHub only for rows that have none. The badge shows the reason ("Closed · completed" / "Closed · not planned").
Scope¶
In Scope¶
Spec v1.3: BR-9 (changed), BR-10, FR-8, the webhook endpoint, the modified app_report table, ReportDto.githubStateReason, EC-14..EC-17 and the webhook acceptance criteria.
Out of Scope¶
- Other issue events (comments, labels, PR links) and in-app notifications.
- Back-filling the state of existing reports (they keep the read-through path until their next event).
- Storing the read-through result.
- Automatic redelivery of missed events (GitHub has none; the owner can redeliver by hand).
Technical Approach¶
Architecture Changes¶
api.github.com ──POST (HMAC)──► GitHubWebhookController ──► GitHubWebhookService ──► AppReportRepository.applyGithubState (conditional UPDATE)
ReportPage (FE) ──► AdminReportController ──► ReportServiceImpl.list ──► stored state, else GitHubIssueClient + GitHubIssueStateCache (as today)
Layers stay web → service → repo; service → config for the secret. No new library.
Key Decisions¶
- No new ADR. ADR-0026 D7 (2026-10-21) covers the endpoint, the secret, the columns and the ordering rule.
- Public path: add
POST /webhooks/githubtoWHITE_LIST_PATH(api/src/main/java/com/canhlabs/funnyapp/utils/AppConstant.java:45-54). That list is used both byWebSecurityConfig(filter/WebSecurityConfig.java:55) and byJWTAuthenticationFilter.shouldNotFilter(filter/JWTAuthenticationFilter.java:104-110), so no JWT is needed and none is parsed. - Raw body, capped: the controller reads
HttpServletRequest.getInputStream().readNBytes(MAX_BODY + 1)withMAX_BODY= 1 MiB and returns 413 above it, before the HMAC check. Check order: 503 (no secret, body not read) → 413 → 401 → 400 → 204, pinned by a controller test that posts a raw body (CWE-770;issuespayloads are tens of KB). No filter inapi/reads the request body first (noContentCachingRequestWrapper;filter/holds only the JWT filter, provider and security config). - Signature:
HmacSHA256(JDKjavax.crypto.Mac) over the raw bytes; comparesha256=<hex>withMessageDigest.isEqual. Verify before any JSON parsing. Header format checked against GitHub's "Validating webhook deliveries" page. - Secret config: add
webhookSecrettoAppProperties.Github(config/AppProperties.java:118-126) withisWebhookConfigured(), andwebhook-secret: ${GITHUB_WEBHOOK_SECRET:}underapp.github(api/src/main/resources/application.yaml:144-147). The name containssecret, which is on the masking list (application.yaml:168-169), and it never enters a DTO. - Transaction: the repo method is
@Modifying @Transactional @Query(...); the service is not transactional otherwise (Spring Data needs a transaction for a modifying query, elseTransactionRequiredException). - Ordering and races: one JPQL
@Modifyingupdate,WHERE status = CREATED AND issueNumber = :n AND (githubStateAt IS NULL OR githubStateAt < :at). Zero rows →existsByStatusAndIssueNumbertellsstalefromunknown-issue. This makes EC-14 and EC-16 hold under concurrent deliveries without locks. - Reason whitelist:
state_reasonis kept only when it is one ofcompleted,not_planned,duplicate,reopened; anything else is stored as null (fitsVARCHAR(16), no 500 after a valid signature). - State mapping:
GitHubIssueState(entity enum) maps toGitHubIssueClient.IssueStateby name (OPEN→OPEN,CLOSED→CLOSED) inresolveStates;toDtokeeps taking the state as a string (:291). - List:
ReportServiceImpl.resolveStates(service/impl/ReportServiceImpl.java:197-229) skips the GitHub call whenrow.getGithubState() != null.toDto(:291-310) addsgithubStateReasonfrom the row (null for read-through rows). - Migration: new file
api/src/main/resources/db/changelog/sql/202610210001-app-report-github-state.sql, picked up byincludeAll: sql/(db/changelog/db.changelog-master.yaml:2-3). Additive, nullable columns only, so a rolling deploy is safe. Latest file today:202610200001-create-app-report.sql. - Controller style: like
web/AdminReportController.java:30-40(@RestController,AppConstant.API.BASE_URL, setter injection), but without@PreAuthorize,@HasPermissionor@RateLimited, since there is no user. - FE badge:
StateBadge(webapp/src/components/report/ReportPage.jsx:34-40) appends· <reason>whengithubStateReasonis set, from new i18n keysstateReason.*next tostate(webapp/src/i18n/locales/en/report.json:52,vi/report.json:52).
Implementation Steps¶
Tasks¶
| ID | Task | Depends on | ~LOC (non-test) | Acceptance criteria |
|---|---|---|---|---|
| WH-1 | Migration 202610210001-app-report-github-state.sql (spec "Modified Tables"); new enum enums/GitHubIssueState { OPEN, CLOSED } (kept out of client so entity does not depend on client); AppReport fields githubState (@Enumerated(STRING)), githubStateReason, githubStateAt (entity/AppReport.java:90-97 area); repo methods applyGithubState(...) (conditional update, returns int) and existsByStatusAndIssueNumber (repo/AppReportRepository.java:15-28); applyGithubState is @Modifying @Transactional |
— | ~40 | Migration SQL matches the spec; columns nullable; applyGithubState carries @Modifying and @Transactional (checked by a reflection test, since the repo is mocked elsewhere); mvn verify passes; entity maps the new columns (checked by the WH-2 service test with a mocked repo and by BeanConstructorTest still passing) |
| WH-2 | AppProperties.Github.webhookSecret + yaml; GitHubWebhookService (verify(signatureHeader, body), handle(event, deliveryId, body) → outcome enum APPLIED/IGNORED/STALE/UNKNOWN_ISSUE); GitHubWebhookController POST /v1/funny-app/webhooks/github returning 204/400/401/503; WHITE_LIST_PATH entry |
WH-1 | ~130 | Unit tests: valid signature + closed/completed → repo update called with CLOSED, completed, payload updated_at; wrong, missing or malformed signature → 401 and repo untouched; blank secret → 503; ping and issues/labeled → 204 IGNORED; other repository.full_name → IGNORED; zero rows updated + exists → STALE, + not exists → UNKNOWN_ISSUE; bad JSON with valid signature → 400; issues event without issue.number → 400; body over 1 MiB → 413 and no HMAC/parse; unknown state_reason (e.g. something_new_and_long) → stored as null. @WebMvcTest (or the AdminReportControllerPermissionTest style) proves the path needs no JWT. Logs carry delivery id, event, action, issue number, outcome; a test with a fake secret and body asserts neither appears in the captured log |
| WH-3 | ReportServiceImpl.resolveStates uses the stored state (mapped by name to IssueState); ReportDto.githubStateReason (dto/admin/ReportDto.java); toDto fills it |
WH-1 | ~25 | ReportServiceImplTest: a CREATED row with stored CLOSED/not_planned → DTO has both and client.state is never called; a row without a stored state → read-through as before (existing tests stay green); FAILED rows → both null |
| WH-4 | FE StateBadge shows the reason; i18n stateReason.{completed,not_planned,duplicate,reopened} in en and vi report.json |
WH-3 | ~20 | ReportPage.test.jsx: a CLOSED row with githubStateReason: 'not_planned' renders "Closed · Not planned"; a row without a reason renders "Closed" only; unknown reason falls back to the raw value; i18n parity test passes; npm run test and npm run lint pass |
| WH-5 | Owner setup + prod check (not run by agents): repo Settings → Webhooks (URL https://canh-labs.com/api/v1/funny-app/webhooks/github, application/json, random secret, Issues only); GITHUB_WEBHOOK_SECRET in /opt/funnyapp/.env, restart; close and reopen a test issue created from the app |
WH-2..WH-4 deployed | — | GitHub "Recent Deliveries" shows 204 for ping and for the close; the Report list shows "Closed · completed" without waiting for the 5-min cache |
Merge order¶
- WH-1 → WH-2 and WH-3 (independent of each other) → WH-4. Every unit merges to
mainon its own: WH-1 is dark (unused columns); WH-2 adds the endpoint, which returns 503 until the secret is set; WH-3 reads the columns, which stay null until events arrive. - Backend before frontend: WH-4 reads
githubStateReason, which is absent (undefined) until WH-3 is deployed, and the badge then shows "Closed" as today.
Files to Modify¶
| Path | Action | Task |
|---|---|---|
api/src/main/resources/db/changelog/sql/202610210001-app-report-github-state.sql |
Create | WH-1 |
api/src/main/java/com/canhlabs/funnyapp/entity/AppReport.java |
Modify | WH-1 |
api/src/main/java/com/canhlabs/funnyapp/repo/AppReportRepository.java |
Modify | WH-1 |
api/src/main/java/com/canhlabs/funnyapp/config/AppProperties.java, api/src/main/resources/application.yaml |
Modify | WH-2 |
api/src/main/java/com/canhlabs/funnyapp/service/GitHubWebhookService.java (+ impl/), web/GitHubWebhookController.java |
Create | WH-2 |
api/src/main/java/com/canhlabs/funnyapp/utils/AppConstant.java |
Modify | WH-2 |
api/src/main/java/com/canhlabs/funnyapp/service/impl/ReportServiceImpl.java, dto/admin/ReportDto.java |
Modify | WH-3 |
webapp/src/components/report/ReportPage.jsx, webapp/src/i18n/locales/{en,vi}/report.json |
Modify | WH-4 |
Tests: service/impl/GitHubWebhookServiceImplTest.java, web/GitHubWebhookControllerTest.java, ReportServiceImplTest.java, ReportPage.test.jsx |
Create / Modify | WH-2..WH-4 |
Testing Strategy¶
- Unit: HMAC verify with a known vector (secret + body → expected hex computed in the test with
Mac), every outcome ofhandle,resolveStateswith stored vs missing state. - Web slice: the webhook path answers without an
Authorizationheader; the admin paths still need one (regression). - Not covered by automated tests: the conditional UPDATE against PostgreSQL (no DB test infra in
api/, same accepted gap as the parent plan); it is checked in WH-5 by closing an issue twice (redelivery →stalein the log). - Gates:
mvn -f api/pom.xml verify(coverage ≥api/.coverage-threshold),npm --prefix webapp run test,npm --prefix webapp run lint.
Rollback Plan¶
- Unset
GITHUB_WEBHOOK_SECRET(endpoint → 503) or delete the webhook on GitHub: the list falls back to stored-or-read-through, and stored states simply stop updating. - Revert WH-3 to return to read-through only. The columns can stay (nullable, unused).
Risks¶
| Risk | Mitigation |
|---|---|
| Secret leak lets anyone set display states | Separate secret from the PAT; rotate in GitHub and the env file; effect is display only (ADR-0026 D7 consequences) |
| Missed delivery leaves a stale state | Owner redelivers from "Recent Deliveries"; accepted in ADR-0026 D7 |
| A proxy changes the body and breaks the signature | Nginx passes the body unchanged by default; WH-5 checks the ping delivery returns 204 |