Last reviewed: 2026-07-19
Direct answer
Label coding agent pull requests by the review surface they need before a reviewer opens the diff. The label should tell the reviewer where risk lives: code behavior, CI workflow syntax, repository instructions, model gateway request handling, or review handoff evidence. Do not use a single “agent change” label as the main signal. That tells the team who or what produced the pull request, but it does not tell them what needs inspection before merge.
A compact starting set is:
review:code-behaviorfor application logic, tests, and user-visible behavior.review:ci-workflowfor GitHub Actions workflow edits, job permissions, triggers, or CI failure repairs.review:repo-instructionsfor AGENTS-style repository guidance that future coding agents will read.review:gateway-contractfor request-shape, response-shape, provider-routing, or redaction changes that depend on CometAPI documentation.review:handoffwhen the pull request mainly packages evidence for a reviewer.
Use more than one label when the pull request crosses surfaces. A coding agent can repair a test, alter a workflow, and update an instruction file in one branch. One broad label hides that coupling. Multiple review-surface labels let the application reviewer, CI owner, and repository-maintenance owner start in the right files.
GitHub pull requests already give teams a place to propose, review, and merge changes from branches. Labels add routing discipline on top of that workflow. They are most useful when paired with a short handoff note that explains changed files, checks run, failed checks, and remaining uncertainty. For a deeper handoff structure, see How to Hand Off Coding Agent Pull Requests for Review . For writing the scope note before the pull request exists, use Write Change Scope Notes Before an Agent Pull Request .
Operator workflow
Setup assumptions: the pull request is open, changed files are visible, CI has either run or is intentionally pending, repository instruction files are included in the diff when changed, and any gateway example uses <API_KEY_PLACEHOLDER> rather than a real credential. The reviewer can see the branch, the pull request description, the file list, and the most recent check result.
Happy-path request plan: first map changed files to review surfaces. Application source, tests, and fixtures get review:code-behavior. Files under workflow configuration get review:ci-workflow. Agent instruction files, repository guidance, or prompt registry changes get review:repo-instructions. Gateway examples, model-routing wrappers, request fixtures, or response parsing changes get review:gateway-contract. Then add a handoff comment that names the labels and gives the reviewer a first file to open for each surface.
For a gateway-related pull request, run one minimal documented chat-completion request only in a staging or local-safe path. Use placeholder-safe fixtures. Verify the request shape, response handling path, and credential redaction behavior against current documentation and local expectations. Do not treat the result as proof of pricing, model availability, throughput, billing behavior, or production readiness.
Error-path check: send one intentionally invalid fixture that should fail before any merge decision relies on the gateway path. The goal is not to test the provider exhaustively. The goal is to confirm that the code path records a clear failure, avoids leaking credentials, and gives the reviewer enough detail to decide whether the contract changed.
Minimum assertions: the pull request has exactly the review labels needed for the changed surfaces, CI evidence is linked or marked pending, instruction-file changes are called out, gateway examples avoid real credentials, and reviewers can tell which files need specialist attention. If a surface cannot be checked, the handoff note should say so plainly.
Pass/fail logging fields:
pr_url: "https://github.com/example-org/example-repo/pull/123"
labels_checked: ["review:code-behavior", "review:ci-workflow"]
changed_surfaces: ["application_code", "workflow_file"]
happy_path_result: "pass|fail|not_run"
error_path_result: "pass|fail|not_run"
credential_redaction: "pass|fail"
reviewer_next_step: "request_changes|approve|needs_specialist"
notes: "placeholder-only summary"
Do not assert model availability, prices, quotas, rate limits, uptime, latency, billing behavior, or account-specific terms from this workflow.
For teams routing coding agent review traffic through a gateway, Start with CometAPI after the request contract is checked against current docs.
Who this is for
This guide is for maintainers who let coding agents open or update pull requests and need reviewers to move quickly without missing the risky part of a change. It fits teams that already use GitHub pull requests, GitHub Actions, repository-level agent instructions, or an API gateway in coding agent workflows.
It is especially useful when several people share review responsibility. A platform engineer may need to inspect workflow syntax and permissions. An application owner may need to inspect behavior and tests. A tooling maintainer may need to inspect instruction files that future coding agents will read. A gateway owner may need to check request fixtures, response handling, and redaction rules. Review-surface labels keep those responsibilities visible.
Key takeaways
- Labels should describe the review surface, not just the authoring tool.
- A pull request can need more than one label when code, CI, instructions, and gateway behavior change together.
- GitHub pull request documentation supports a branch-based propose-review-merge workflow; labels help reviewers focus inside that workflow.
- GitHub Actions workflow syntax is the right reference for workflow-file review, not guesses from a failing run.
- Repository instruction changes deserve their own label because later coding agent sessions may inherit them.
- CometAPI request examples should stay source-backed and placeholder-only until exact contract details are checked.
Sources checked
- GitHub pull requests documentation - accessed 2026-07-19; purpose: verify pull request review and collaboration boundaries.
- GitHub Actions workflow syntax documentation - accessed 2026-07-19; purpose: verify workflow permission configuration areas.
- OpenAI Codex AGENTS.md guidance - accessed 2026-07-19; purpose: verify repository instruction-file context for coding agents.
- CometAPI chat completions reference - accessed 2026-07-19; purpose: verify chat completion contract areas.
Contract details to verify
| Area | What to verify | Source URL | Accessed | Safe candidate wording |
|---|---|---|---|---|
| Pull request review routing | Pull requests can propose, review, and merge code changes, and reviewers inspect proposed changes before merge. | https://docs.github.com/en/pull-requests | 2026-07-19 | “Use labels to point reviewers to the riskiest changed surface before merge.” |
| CI workflow changes | Workflow-file edits should be checked against GitHub Actions workflow syntax. | https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax | 2026-07-19 | “Mark workflow edits separately from application-code edits.” |
| Repository instructions | Agent-readable repository instructions can affect later coding agent behavior. | https://github.com/openai/codex/blob/main/docs/agents_md.md | 2026-07-19 | “Give instruction-file changes a dedicated review label.” |
| Gateway request checks | Chat-completion request examples should be checked against the current CometAPI reference before reuse. | https://apidoc.cometapi.com/api/text/chat | 2026-07-19 | “Verify request shape and redaction behavior against current gateway docs.” |
Failure modes
- Evidence gap: the reviewer cannot inspect the failing log, source page, pull request, or local command output. The safe action is to stop and record the missing evidence instead of guessing.
- Scope drift: the agent edits files that are not connected to the observed failure. Keep the repair tied to the failing signal and leave unrelated cleanup for a separate pull request.
- Environment mismatch: the local check uses different versions, credentials, feature flags, or runtime settings than the hosted path. Record the mismatch before treating the result as proof.
- Unreviewed fallback: the agent changes models, endpoints, permissions, or retry behavior to make a run pass without preserving the review boundary. Treat access and provider failures as operational blockers for the pull request.
- Weak handoff: the final note says the issue is fixed but omits the command, result, changed files, and remaining uncertainty. That makes the next reviewer repeat the investigation.
Reader next step
Add the five-label starter set to one active coding agent pull request, then rewrite the pull request handoff note so each label has a matching evidence line. Start with the changed file list. For every file group, write the surface it belongs to, the check that supports it, and the reviewer who should look first. If the pull request includes a gateway fixture, confirm that credentials are represented only as <API_KEY_PLACEHOLDER> and that the cited CometAPI page is the current public reference for the request family you are using.
A practical next review comment can be short:
Review surfaces:
- review:code-behavior: app files and tests changed; local test result attached.
- review:ci-workflow: workflow trigger edited; checked against workflow syntax docs.
- review:gateway-contract: request fixture changed; placeholder credential only.
First reviewer action: inspect the workflow diff before approving the behavior change.
If the pull request does not fit any label, do not create a vague catch-all label immediately. First ask what kind of evidence a reviewer needs before merge. The answer usually reveals the missing surface.
FAQ
Should every coding agent pull request get an agent label?
Use an ownership or authoring label if it helps queue management, but do not stop there. The more important labels describe what needs review: code behavior, workflow syntax, repository instructions, or gateway request handling.
What if a pull request changes both tests and a workflow file?
Apply both labels. The code reviewer can inspect tests while the CI reviewer checks workflow syntax, permissions, triggers, and failure evidence.
Should gateway labels include model names or pricing notes?
No. Keep the label focused on the contract area that needs review. Verify model names, pricing, limits, and account-specific terms only from current provider documentation or account evidence.
Can labels replace a review checklist?
No. Labels route attention. A checklist still records the evidence reviewers used before approving, requesting changes, or escalating.