Start at the missing result
A developer opens a pull request. The integration says Connected, the webhook dashboard shows a successful response, and the pull request has no review. Reconnecting the account might feel like the obvious fix. First establish which part of the workflow actually stopped.
A review travels through several independent steps: an event arrives, a job is accepted, a worker examines a particular revision, and a result is submitted to GitHub. Success at one step does not establish success at the next. A saved report inside a tool and a visible GitHub review are different outputs. Diagnose the output the developer expected.
This field note describes a general engineering method, with a fictional pull request as an example. The receipt format and recovery controls are general design recommendations, not a description of shipped AntiCode features.
Separate acknowledgement from durable acceptance
GitHub’s webhook guidance calls for a 2xx response within ten seconds and suggests processing asynchronously. That response records a delivery outcome; it does not prove that analysis completed or that a reviewer saw a comment. The receiver needs a deliberate boundary between accepting responsibility for work and merely receiving a network request.
For a review service, a useful design is to validate the request and durably record the work before acknowledging it. If work exists only in a process’s memory, a restart after the response can leave GitHub reporting success while the job disappears. A queue also needs a running consumer: an accepted job can remain untouched indefinitely.
Keep acknowledgement time, durable acceptance time, first worker attempt, and final outcome separate in diagnostics. A single green “Connected” badge cannot explain where a stalled run is waiting.
Give one revision a traceable receipt
Consider the fictional repository example/widgets, pull request #42. Its opening event references commit A. Later, a push changes the head to commit B. Without a shared record, a developer may read the completion of A as evidence that B was reviewed. The record should connect the event, selected comparison, analysis, and external result.
The following JSON is an illustrative operator record for a run whose analysis finished but whose publication response is uncertain. Its shortened revisions and identifiers are placeholders. It is not an AntiCode API response.
- Record repository and installation identity so similar PR numbers cannot be confused across customers.
- Record which revision and scope were actually examined; “completed” should not conceal omitted files.
- Keep external review identifiers and the result URL when available.
- Limit diagnostic access and retention. Exclude credentials, raw webhook bodies, private source snippets, and unnecessary personal data.
{
"delivery_id": "example-delivery-id",
"repository": "example/widgets",
"pull_request": 42,
"head_revision": "commit-A",
"base_revision": "base-X",
"job_id": "example-job-17",
"analysis_state": "completed",
"coverage": "selected changed text files",
"finding_count": 2,
"publication_state": "unknown",
"github_review_id": null
}Investigate backwards from GitHub
Start with the expected review on the pull request. If your service recorded a review ID, retrieve that review and inspect its state, revision, and submission time. GitHub’s review API distinguishes a pending review from a submitted one: creating a review without an event leaves it pending. An allocated ID alone is therefore insufficient evidence of a published review.
If no submitted review exists, inspect the publication attempt. For the supported fine-grained tokens, GitHub documents Pull requests write permission for creating reviews. Repository access, credentials, and the actual API response still matter. Do not expand access to every repository simply because one request failed.
Next inspect the analysis result, the worker attempt, the accepted job, and finally the incoming delivery. Follow the same identifiers throughout. A worker that never started needs a different repair from an inline comment rejected because its location no longer describes the diff.
- Submitted review found: check that it belongs to the intended pull request and revision.
- Analysis completed, publication failed: fix the posting error without assuming the analysis must run again.
- Job accepted, no attempt recorded: examine worker availability, scheduling, and admission limits.
- No accepted job: examine event subscription, event action, delivery outcome, and receiver validation.
Treat inline comments as revision-bound output
A general message in the PR conversation and a comment attached to a diff line are separate interfaces. For line-based review comments, GitHub documents a commit and location including the file path, line, and side. Multiline comments also need their start location. A finding with a plausible explanation still needs a valid location before it can appear inline.
Suppose the analysis of A found a problem on a line removed in B. Do not silently attach the old finding to whichever line now has the same number. Reconcile the review against the new comparison. Depending on the product’s policy, retain it as historical evidence or request a fresh review. Neither an outdated comment nor a failed inline submission should appear as “the current change passed.”
Recover deliberately instead of posting twice
GitHub does not automatically redeliver failed webhook deliveries. Recovery can be manual or scheduled through the delivery APIs. Its guidance also states that a requested redelivery keeps the original X-GitHub-Delivery value. Use that identity together with recorded processing state when deciding what recovery should do.
Receiving an event twice and performing the work twice are different things. An already completed and published job should not create another identical review. A delivery that was received but never accepted durably still needs recovery. A failed publication may need another posting attempt, while successful analysis can remain useful for the same revision.
A timeout creates a harder case: GitHub may have accepted the review before the caller lost its response. Before retrying, reconcile using the run’s recorded identifiers and reviews for the relevant change. Design for this uncertainty explicitly. A delivery table alone does not guarantee exactly-once comments, particularly when concurrent workers can submit the same result.
Make quiet outcomes explicit
“No findings” should mean that analysis completed within a stated scope and saved no supported findings. It should not stand for a skipped draft, an exhausted allowance, an unavailable worker, missing permissions, or a failed request. Name those outcomes separately and give the operator an appropriate next action.
For AntiCode users, verify what the particular workflow promises. Viewing a saved report proves that a report is available in the workspace. To establish GitHub delivery, look for the submitted result on the intended PR and revision. A local Mac update or a successful sign-in is not a substitute for that check.
Finish a repair with a small authorized test change. Observe its arrival, accepted job, completed analysis, and submitted result. In a controlled test environment, repeat the delivery and check that recovery does not create duplicate output; then make a corrected follow-up revision and verify that its result is distinct. Keep the test’s scope and observed outcome in the release record. That evidence is more useful than another screenshot of a connected account.
Further reading
Put it into practice
Start with a small change you are authorized to review. Follow the AntiCode setup guide, inspect each finding, and keep your tests and human approval in the loop.