Use Case: Automated PR Review Comment

Complexity: Starter
Trigger: GitHub pull_request.opened
Deliverable: Structured code-review comment posted to the PR

Goal

Reduce the feedback loop between a PR author and reviewers. Every time a pull request is opened Xema automatically analyses the diff and posts a structured summary comment with:

  • files changed and their purpose
  • potential issues detected
  • suggested review focus areas

Human reviewers get a head-start; the agent does the boring part.

Trigger

A GitHub webhook fires when a PR is opened against the main branch. The connector-gateway-api normalises the event and dispatches a ScmWebhookEvent.PULL_REQUEST_OPENED envelope to workflow-engine-api, which matches it to this workflow.

Steps

StepTypeDescription
fetch-diffAgent actionFetches the PR diff from the SCM API
reviewAgent actionAnalyses the diff; produces a code-review deliverable
post-commentHTTP actionPosts the deliverable content as a PR comment via SCM API

Deliverables

  • code-review — A markdown document containing file-change summary, issues detected, and review focus areas. Stored as an artifact and posted as a PR comment.

Workflow YAML

yaml
1apiVersion: workflow/v1alpha1
2kind: Workflow
3metadata:
4  name: automated-pr-review
5  version: "1.0.0"
6
7on:
8  webhook:
9    provider: github
10    event: pull_request.opened
11    filters:
12      targetBranch: main
13
14inputs:
15  prNumber:
16    type: number
17    source: "{{ event.pull_request.number }}"
18  repoFullName:
19    type: string
20    source: "{{ event.repository.full_name }}"
21  diffUrl:
22    type: string
23    source: "{{ event.pull_request.diff_url }}"
24
25jobs:
26  fetch-diff:
27    action: scm-connector-api.fetch-[email protected]
28    input:
29      repoFullName: "{{ inputs.repoFullName }}"
30      prNumber: "{{ inputs.prNumber }}"
31
32  review:
33    needs: [fetch-diff]
34    action: [email protected]
35    input:
36      task: |
37        Review the following pull request diff and produce a structured code-review document.
38        Include: summary of changes, files affected, potential issues, and suggested review focus areas.
39        Format as markdown with clear sections.
40      context:
41        diff: "{{ jobs.fetch-diff.outputs.diff }}"
42      deliverableSpec: code-review-v1
43    output:
44      artifactKey: code-review
45
46  post-comment:
47    needs: [review]
48    action: scm-connector-api.post-pr-[email protected]
49    input:
50      repoFullName: "{{ inputs.repoFullName }}"
51      prNumber: "{{ inputs.prNumber }}"
52      body: "{{ jobs.review.outputs.artifact.content }}"

Extending It

  • Conditional posting — Only post the comment if review.outputs.issueCount > 0.
  • Severity gating — Add a gate.humanApproval step that blocks merge if the agent flags a high-severity issue.
  • Multi-provider — Add a second on.webhook block for gitlab using the same workflow body.
  • Custom spec — Swap code-review-v1 for your own deliverable spec to enforce team-specific review criteria.

Next: Scheduled Security Audit →