Integrations — Reviewing XM Cloud / Next.jspull requests with coding agents safely

Introduction

This guide is for Sitecore XM Cloud + Next.js teams who want coding agents to help with GitHub pull‑request review, without breaking serialization, leaking secrets, or shipping random refactors. I describe how I plug these tools into my own XM Cloud projects.

I focus on:

GitHub + Claude Code
GitHub + OpenAI Codex
GitHub + Google Gemini Code Assist

…plus a short section on Bitbucket and Azure DevOps.

Everything here assumes XM Cloud projects like the official Sitecore/xmcloud-starter-js template with /authoring for Sitecore Content Serialization items and Next.js examples. (GitHub)

When coding agents actually help on XM Cloud

I reach for agents on XM Cloud pull requests when:

I am the only reviewer or the team is small.
Pull requests touch frontend + YAML + config and I want a quick summary.
I want tests, docs, and small refactors to keep up with feature work.
I already enforce non‑negotiables (lint, type‑check, build) in continuous integration.

I avoid or restrict agents when:

governance forbids AI‑generated code (some projects explicitly do this), (TechRadar)
pull requests contain licensing‑sensitive code or customer data,
changes are pure content or item moves where human context matters more than code.

The goal is to let agents summarize, review, and suggest — continuous integration and humans still decide what ships.

The core pattern I use (Claude, Codex, and Gemini)

At a high level, my target flow looks like this:

Common ingredients for me are:

Guardrails in the repo
- AGENTS.md for Codex and generic agents. (OpenAI Developers)
- CLAUDE.md for Claude Code. (Claude Code)
- Optional: reuse XM Cloud starter’s LLMs.txt and copilot-instructions.md. (GitHub)
GitHub integration
- Official apps or actions from Anthropic, OpenAI, and Google.
- Optional custom GitHub Actions that call their APIs.
XM Cloud‑aware prompts
- Prompts that are explicit about serialization, Next.js App Router, and config files.
Advisory only
- Agents leave comments or checks.
- Continuous integration and humans own the final decision.

The rest of this post shows how I do this with minimal moving parts.

Guardrails with `AGENTS.md` (Codex‑first, others benefit)

OpenAI Codex Cloud reads AGENTS.md automatically and applies your “Review guidelines” when it reviews GitHub PRs. (OpenAI Developers)

Other agents don’t have a special contract with AGENTS.md, but they still see it as a normal file — so it’s the right place to spell out your rules once and reuse them everywhere.

Recommended files for an XM Cloud repo

At the repo root:

AGENTS.md — cross‑agent rules and review checklist (Codex reads this natively).
CLAUDE.md — Claude‑specific instructions (Claude Code Actions use this). (Claude Code)
LLMs.txt / copilot-instructions.md — from xmcloud-starter-js, already tuned for XM Cloud. (GitHub)

You can keep them DRY by having CLAUDE.md and LLMs.txt reference the same core rules defined in AGENTS.md.

Sample `AGENTS.md` for Sitecore XM Cloud + Next.js

This is intentionally short so agents reliably read it:

# AGENTS.md — XM Cloud + Next.js

This repo is a Sitecore XM Cloud + Next.js project based on the official XM Cloud starter.

For general AI patterns and component conventions, also see:
- LLMs.txt
- copilot-instructions.md

## Review guidelines

- **Serialization / content**
  - Treat `/authoring` (Sitecore Content Serialization) as read-only unless the PR clearly intends to change items.
  - If YAML changes under `/authoring/items` look accidental, call them out instead of editing them.
  - Never invent GUIDs or paths for Sitecore items; prefer existing templates and modules.

- **Configuration & secrets**
  - Do not propose storing secrets in `.env*`, `xmcloud.build.json`, or `sitecore.json`.
  - Assume `.env*`, `xmcloud.build.json`, and `sitecore.json` are sensitive; suggest changes in comments, not direct edits.
  - Flag any hard-coded API keys, tokens, or connection strings.

- **Next.js (App Router)**
  - Prefer small, focused components under existing folders instead of new top-level structures.
  - Avoid blocking data-fetch in Client Components when Server Components or route handlers are available.
  - Flag `any` types, unhandled promise rejections, and missing error boundaries for new features.

- **Testing**
  - When suggesting changes, recommend existing scripts only (from package.json), e.g. `npm run lint`, `npm test`, `npm run e2e` if they exist.
  - Prefer adding or updating tests instead of disabling them.

- **Performance & security**
  - Call out large bundle additions, unnecessary client-side state, and unbounded loops or polling.
  - Flag unsafe HTML rendering (`dangerouslySetInnerHTML`) and unsanitized input where it appears.

## Output format

When you review a pull request, respond with:

1. A 3–5 line summary of what changed.
2. A list of findings grouped by file, with severity: P0 (must fix), P1 (should fix), P2 (nice to have).
3. Suggestions for tests or documentation updates, if applicable.

Claude‑specific `CLAUDE.md` (thin wrapper)

Claude Code Actions recommend a CLAUDE.md describing project rules. (Claude Code)

You can keep it tiny and reuse AGENTS.md:

# CLAUDE.md

This repo is Sitecore XM Cloud + Next.js.

When reviewing or editing code:

- Follow the rules in AGENTS.md (review guidelines, testing, security).
- Prefer minimal diffs; do not restructure the project unless explicitly asked.
- Do not modify files under `/authoring` unless the task is clearly about serialized items.

That’s it. With these files in place, I am ready to wire up the three agents.

GitHub: wiring Claude Code, Codex, and Gemini into PRs

This section assumes:

I already have GitHub Actions enabled on the XM Cloud repo.
Continuous integration runs basics (lint, tests, build) on pull_request events.

On top of that I add non‑blocking AI review.

Claude Code on GitHub PRs

Claude Code provides an official GitHub Action and GitHub App that can respond to @claude mentions and also run fully automated workflows. (Claude Code)

What you get

PR and issue review via @claude comments.
Automated flows (e.g. run on every PR open) with custom prompts.
Respect for your CLAUDE.md rules.

Minimal setup

Install the Claude GitHub app for your repo or org. (Claude Code)
Add ANTHROPIC_API_KEY as a repository secret (if you use the direct Anthropic API). (Claude Code)
Copy one of the example workflows (e.g. claude.yml) from the anthropics/claude-code-action repo into .github/workflows. (GitHub)

A basic pattern from the docs is:

Trigger on pull_request (opened, synchronize, reopened).
Use anthropics/claude-code-action@v1 in a job.
Pass:
- anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
- prompt: "/review" or a custom prompt.
- Optional claude_args (e.g. model, max turns). (Claude Code)

I keep this job non‑blocking by not marking it as a required check in branch protections.

XM Cloud‑specific prompt for Claude

Example prompt value for Claude Code Action:

/review

You are reviewing a pull request in a Sitecore XM Cloud + Next.js repo.

- Always read AGENTS.md and CLAUDE.md first.
- Focus on:
  - Breaking changes to /authoring (serialization) and xmcloud.build.json
  - Next.js App Router patterns, data fetching, and error handling
  - Obvious security issues and missing tests

Return:
- A short summary
- P0/P1/P2 findings grouped by file
- Suggested tests or docs updates

I set this as prompt in the workflow, or use a custom slash command pattern described in the docs. (Claude Code)

OpenAI Codex Code Review with AGENTS.md

OpenAI’s Codex Cloud has a native GitHub integration:

You connect your GitHub repo from Codex Cloud.
Enable “Code review” for that repo in Codex settings.
On GitHub, comment @codex review in a PR to trigger a review. (OpenAI Developers)

Codex will then:

Analyze the PR diff.
Leave a standard code‑review in the PR.
Read AGENTS.md (including subfolder versions) and apply your Review guidelines to each file. (OpenAI Developers)

Minimal setup I use

Go to Codex Cloud and connect my GitHub account and repo. (OpenAI Developers)
In Codex settings for that repo, enable Code Review. (OpenAI Developers)
Ensure AGENTS.md at the repo root has a ## Review guidelines section (see sample above). (OpenAI Developers)

XM Cloud‑specific tweaks to AGENTS.md

Because Codex uses AGENTS.md directly, that’s where I encode XM Cloud rules:

Call out /authoring as SCS and mostly read‑only.
Mention xmcloud.build.json as deployment config, not a playground for random edits. (GitHub)
Add rules around not hard‑coding item paths or GUIDs in React components.

Optional: custom Codex GitHub Action

If you want more control (e.g. only run on large PRs or certain paths), OpenAI provides:

A Codex SDK and example GitHub Action (openai/codex-action) to build your own PR bot. (OpenAI Cookbook)

The pattern:

Trigger on pull_request.
Checkout the repo and compute the diff.
Call Codex via its SDK or the GitHub Action.
Post a comment back to the PR.

In that custom prompt, explicitly say “read AGENTS.md” and restate the XM Cloud‑specific rules you care about most.

Gemini Code Assist on GitHub

Gemini Code Assist on GitHub is Google’s agent that:

Summarizes pull requests.
Provides in‑depth code review comments.
Is triggered via /gemini comments on PRs once installed. (Google for Developers)

Minimal setup

Open the Gemini Code Assist GitHub App page and install it for your user or org. (Google for Developers)
Select which repositories to enable Code Review on. (Google for Developers)
After setup, Gemini will:
- Summarize PRs automatically.
- Respond to PR comments that include /gemini with more detailed review. (Google for Developers)

Gemini uses the repo as context, so it will see AGENTS.md, CLAUDE.md, LLMs.txt, and so on, just like any other file. (Google for Developers)

XM Cloud‑specific prompt for /gemini

Example comment on a PR:

/gemini

Review this PR as a Sitecore XM Cloud + Next.js code reviewer.

Read AGENTS.md first. Focus on:
- Accidental changes under /authoring (serialization)
- Changes to xmcloud.build.json and sitecore.json
- Next.js App Router correctness and performance
- Missing tests and docs

Return summary + P0/P1/P2 findings.

You can keep that in a PR template so reviewers can just paste or tweak it.

Prompt templates for XM Cloud PR reviews

These templates are designed to be reused across all three tools (Claude, Codex, Gemini). You can:

Use them inline (e.g. @codex review for <prompt>).
Or pass them to actions (prompt: for Claude Code Action, request body for Codex SDK / Gemini API).

General XM Cloud PR review prompt

You are reviewing a GitHub pull request for a Sitecore XM Cloud + Next.js project.

Inputs you will be given:
- The unified diff for this PR.
- The PR title and description.
- The contents of AGENTS.md and (if available) CLAUDE.md.
- Optionally, a linked user story or task description.

Follow these rules:

1) Always read AGENTS.md first and obey its "Review guidelines".
2) Treat /authoring (Sitecore Content Serialization) as mostly read-only.
   - If items change, check that the changes look intentional and consistent.
3) Treat xmcloud.build.json and sitecore.json as configuration sources of truth.
   - Flag hard-coded values in React components that should come from content or config.
4) For Next.js:
   - Prefer Server Components or route handlers for data fetching when possible.
   - Flag blocking calls in Client Components and missing error handling for new routes.
5) Security:
   - Highlight secrets, tokens, or connection strings in code.
   - Call out unsafe HTML rendering and obvious input validation gaps.

Output:

- A 3–6 line summary of what changed.
- Findings grouped by file, each tagged with severity (P0/P1/P2).
- Concrete suggestions for tests and docs, if any.
- Keep the whole response under ~400 words.

“Add tests and stories” prompt

Use this when you want agents to focus only on tests / docs:

You are an assistant for a Sitecore XM Cloud + Next.js repo.

Based on the diff and AGENTS.md:

1) Propose specific unit, integration, or Playwright tests for the changed code.
2) Suggest new or updated Storybook stories (if the project uses Storybook) for any React components that changed.
3) Do NOT propose changes to /authoring or deployment config; tests and docs only.

Return:
- A list of test files to add or edit, with example test case descriptions.
- A list of Storybook stories to add or adjust, if applicable.

You can plug this into:

Claude Code (prompt: in the GitHub Action).
Codex Cloud task (@codex <prompt> on the PR).
Gemini (/gemini comment) after summarization.

Linking PR reviews to user stories and tasks

You can make agents story‑aware with a simple convention:

Reference the story in the branch and PR

Example:
- Branch: feature/SXM-123-new-header
- PR title: SXM-123: Add new global header
- PR body includes a link to the story (GitHub Issue, Jira, Azure Boards work item, etc.).
Fetch the story text in CI

In a GitHub Action you can:
- Parse the story ID from the branch name or PR title.
- Call your tracker’s REST API to retrieve the story description.
- Pass that text as spec or user_story into the agent prompt.
For GitHub Issues, you can use the GitHub REST API directly; for Jira/Azure Boards, use their REST endpoints.

Extend your prompt

Add this to any of the prompts above:

You will also receive the associated user story:

<user_story>

- First, restate in 2–3 lines what the story requires.
- Then check whether the code changes actually implement that story.
- Call out obvious mismatches between the story and the implementation.

This pattern works the same regardless of whether you call Claude, Codex, or Gemini from GitHub Actions or via their official GitHub integrations.

Bitbucket and Azure DevOps (high‑level pattern)

If your XM Cloud code lives in Bitbucket or Azure DevOps, the pattern is the same, but you wire it up with their CI and REST APIs instead of GitHub Apps.

Bitbucket (Cloud)

Key building blocks:

Bitbucket Pipelines to run CI jobs. (Atlassian Developer)
Pull request REST API to read PRs and post comments programmatically. (Atlassian Developer)

High‑level approach:

Add AGENTS.md and (optionally) CLAUDE.md to your XM Cloud repo as above.
In a Pipeline step:
- Fetch the PR diff via Bitbucket’s REST API.
- Call Claude, Codex, or Gemini via their HTTP APIs with the same prompts you use on GitHub.
- Post a review summary back as a PR comment using the Bitbucket REST API.
Keep the step non‑blocking so human reviewers still decide.

You can start with a manual “comment‑trigger” pattern (run the pipeline only when a specific keyword is added to the PR) and later automate for all PRs.

Azure DevOps Repos