Last reviewed: 2026-07-18
Direct answer
Contain CometAPI gateway changes by putting each gateway experiment in its own Git worktree, keeping the branch focused, and opening a pull request that shows only the gateway diff plus the smoke-test record. Git documents worktrees as linked working trees attached to the same repository, which is exactly the property a coding-agent team needs when a gateway change should be tested without disturbing the main checkout. The pull request then becomes the place to compare the branch, discuss the change, and keep CI results attached to the proposed update.
Use this workflow when the change touches a CometAPI request wrapper, model-routing fixture, response parser, or usage trace. The goal is not to prove broad provider behavior. The goal is to prove that one branch made one documented gateway change, checked the expected request family, handled one controlled failure, and left a clean record for review.
Setup assumptions: the repository starts from a clean main checkout; the agent receives one branch name and one worktree path; CometAPI credentials live in a local secret store outside committed files; the operator has the current CometAPI documentation open for the endpoint family being touched; and the repository already has a pull request and CI workflow convention.
Happy-path request plan: create a dedicated worktree, make the smallest gateway fixture or wrapper change, run one sanitized request using contract details verified in the linked CometAPI Responses page or model overview, and record only placeholder-safe results. If the fixture needs an authentication placeholder in checked-in examples, use <API_KEY_PLACEHOLDER> and keep real values outside the repository.
Error-path check: run the same fixture with an invalid placeholder credential, incomplete placeholder payload, or disabled local secret. The expected result is a controlled failure that stays within the intended gateway path. It should not silently fall through to an unrelated route, switch endpoint families, rename the model target, or mask the failed request behind a generic success message.
Minimum assertions: the diff remains limited to the worktree branch; the pull request shows only gateway-related files, fixture files, and the smoke-test note; CI runs on the branch or pull request according to the repository workflow; request fields are copied only after the current source page has been checked; and logs contain no credentials, full prompts, full responses, account-specific values, prices, limits, or uptime claims.
Pass/fail logging fields: worktree_path, branch_name, docs_url, request_family, changed_files, happy_path_result, error_path_result, ci_run_url, redaction_check, scope_check, and maintainer_notes.
What not to assert: do not claim exact model availability, pricing, quotas, billing behavior, latency, uptime, or production readiness from a local smoke test. Those claims need their own evidence. This workflow only contains the diff and makes the review trail easier to trust.
For the broader isolation pattern, read Use Git Worktrees to Keep Parallel Coding Agents Isolated . For gateway routing context, pair this with Route Coding Agent Model Calls Without Endpoint Drift .
Start with CometAPI when you are ready to route a documented gateway check through a dedicated worktree branch.
Who this is for
This guide is for engineering teams that let coding agents edit model gateway code, request fixtures, response-shape checks, or review helpers. It fits teams that already use pull requests and CI, and want a repeatable way to keep CometAPI-related changes separate from unrelated repository edits.
It is also useful when two agents are working near the same gateway code. One agent might be improving a request wrapper while another is updating documentation comments or CI fixtures. Without a worktree boundary, those tasks can collide in the same checkout and blur the reason a test passed or failed. With a dedicated worktree, each branch has a path, a purpose, and a handoff record.
This is not a substitute for production monitoring, account-level billing checks, or provider support. It is a containment workflow for code review. If the change depends on an unavailable account setting, a private dashboard, or credentials the agent cannot inspect, stop at the evidence you have and record the missing input plainly.
Key takeaways
- Use one worktree per CometAPI gateway change so the agent can test without disturbing the main checkout.
- Keep the branch narrow: gateway fixture, request wrapper, documentation comments, and the smoke-test note belong together; unrelated refactors do not.
- Verify endpoint family, authentication expectations, request fields, response fields, and model references against current CometAPI documentation before copying examples into code.
- Let the pull request collect the diff, CI result, and review discussion instead of spreading evidence across chat messages and local notes.
- Keep logs sanitized; placeholders are enough to prove the workflow without exposing secrets or account-specific output.
- Treat fallback-route changes as separate work unless the branch was explicitly opened to test fallback behavior.
Smoke-test workflow
Create the worktree and branch from the repository root:
git worktree add ../gateway-check contain-cometapi-gateway-diffs
cd ../gateway-check
Then make the smallest gateway fixture change. Use placeholders in any example file:
REQUEST_ENDPOINT_FROM_DOCS=<verified endpoint from linked documentation>
AUTH_HEADER_FROM_DOCS=<verified auth header format>
API_KEY=<API_KEY_PLACEHOLDER>
REQUEST_BODY=<minimal documented placeholder request>
Before running anything, write a short scope note in the branch. A good note says which wrapper, fixture, or parser can change; which files are out of scope; which CometAPI page is being used; and which result fields are safe to log. This gives the agent a boundary it can check while editing.
Run the happy path with a local secret value that is never committed. Run the error path with <API_KEY_PLACEHOLDER> or another invalid placeholder value. If the happy path fails, keep the failure. Do not switch endpoints, rename the model target, add retries, or loosen assertions just to make the branch look green. If the error path succeeds unexpectedly, treat that as a serious signal: the fixture may not be checking authentication or routing the way the team expects.
Open a pull request from the worktree branch and let the configured workflow run against the branch. GitHub Actions workflow syntax defines how workflows respond to events and jobs, so the repository’s own workflow file should decide which checks run. The article does not need to prescribe a universal event trigger; it only needs the branch to collect the configured check result.
Use this sanitized log record after the smoke test:
{
"worktree_path": "../gateway-check",
"branch_name": "contain-cometapi-gateway-diffs",
"docs_url": "https://apidoc.cometapi.com/api/text/responses",
"request_family": "responses",
"changed_files": ["gateway_fixture_placeholder"],
"happy_path_result": "pass_or_fail_placeholder",
"error_path_result": "controlled_failure_placeholder",
"ci_run_url": "https://github.com/ORG/REPO/actions/runs/RUN_ID_PLACEHOLDER",
"redaction_check": "no credentials, full prompts, or full responses recorded",
"scope_check": "gateway-only diff",
"maintainer_notes": "short summary of what changed and what remains uncertain"
}
After the pull request is open, compare it with How to Produce Reviewable Diffs From Coding Agent Sessions if the branch includes more than the gateway fixture. If the worktree is no longer needed after the branch is merged or closed, use your team’s cleanup practice and confirm that no uncommitted notes or local-only findings need to be preserved first.
Sources checked
- Git worktree documentation - accessed 2026-07-18; purpose: verify parallel worktree isolation commands and constraints.
- GitHub pull requests documentation - accessed 2026-07-18; purpose: verify pull request review and collaboration boundaries.
- GitHub Actions workflow syntax documentation - accessed 2026-07-18; purpose: verify workflow permission configuration areas.
- CometAPI models overview - accessed 2026-07-18; purpose: verify model catalog discovery guidance.
- CometAPI responses reference - accessed 2026-07-18; purpose: verify responses endpoint contract areas.
Contract details to verify
| Area | What to verify | Source URL | Accessed | Safe candidate wording |
|---|---|---|---|---|
| Worktree isolation | Confirm the command and role of linked working trees before creating an agent branch. | https://git-scm.com/docs/git-worktree | 2026-07-18 | “Use a separate Git worktree for the gateway branch.” |
| Pull request review | Confirm the pull request is the review surface for the branch diff and discussion. | https://docs.github.com/en/pull-requests | 2026-07-18 | “Open a focused pull request for the gateway change.” |
| CI workflow configuration | Confirm the repository workflow syntax used for branch or pull request checks. | https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax | 2026-07-18 | “Let the configured workflow run on the branch or pull request.” |
| Response contract | Confirm endpoint, authentication, request fields, and response fields in the current Responses documentation before writing fixtures. | https://apidoc.cometapi.com/api/text/responses | 2026-07-18 | “Use placeholders until the exact request contract is checked in the linked documentation.” |
Failure modes
Evidence gap: the agent 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. A missing source should not become a confident endpoint claim.
Scope drift: the agent edits files that are not connected to the observed gateway change. Keep the repair tied to the failing signal and leave unrelated cleanup for a separate task. If formatting touches many files, separate that from the gateway branch.
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, not as a reason to quietly widen the branch.
Unsafe logging: the smoke test records credentials, full prompts, full responses, account-specific values, prices, limits, or uptime claims. Replace those values with placeholders and keep the log focused on pass/fail evidence.
Weak handoff: the final note says the issue is fixed but omits the command, result, changed files, and remaining uncertainty. That makes the next operator repeat the investigation.
Reader next step
Before you let a coding agent touch CometAPI gateway code, create a short branch brief with four lines: the worktree path, the gateway file or fixture allowed to change, the CometAPI documentation URL to check, and the sanitized logging fields you expect in the pull request. Then open the worktree branch and run one happy-path and one controlled failure-path check before requesting review.
If your team is still defining the gateway boundary, start with Preflight Request Fixtures for Coding Agents Using CometAPI and Set Safe Permission and Secret Boundaries for Coding Agents . Those two checks make the worktree pattern easier to apply because the agent already knows where placeholders, credentials, and request fixtures belong.
FAQ
Why use a worktree instead of a normal branch checkout?
A branch checkout can work, but a separate worktree gives the agent a dedicated directory for the gateway change. That makes it easier to compare, test, and discard the branch without disturbing the main checkout.
Should the article name a specific CometAPI model?
No. Model names and availability should be verified in the current CometAPI model documentation at the time of the change. The smoke test should record the request family and documentation URL, not unsupported availability claims.
What belongs in the pull request?
Include the gateway diff, fixture change, CI result, and sanitized smoke-test record. Keep unrelated cleanup or broad refactors out of the same branch.
What should logs omit?
Logs should omit real credentials, full prompts, full responses, account-specific values, prices, limits, and uptime claims. Use placeholders and short pass/fail notes instead.
What if the CometAPI page changed since the fixture was written?
Pause the code change long enough to compare the fixture with the current page. If the contract details are different, update the branch note and fixture together so the pull request shows both the source check and the code change.