Pull Request Factory for AI Coding Agents

A pull request from an AI coding agent is only useful if the reviewer can trust the trail that produced it.

The goal is not to find one magic coding CLI. The goal is to build a repeatable factory from issue to review.

[[VIDEO_EMBED]]

That is the control plane many tutorials skip. They show a coding agent writing files, but not the rails that keep the run narrow, disposable, testable, and easy to reject.

I run a business, not a software consultancy. I use AI agents because better internal systems make the business easier to operate.

That changes the standard. I do not need an agent that feels like a teammate. I need a worker that accepts a spec, works in a sandbox, leaves logs, and hands me evidence.

GitHub Issues, the work-tracking feature in GitHub’s code hosting platform, can track ideas, tasks, feedback, and bugs, according to GitHub Docs, checked 10 August 2026.

That is the right starting point because the work needs a record before it needs code.

GitHub pull requests are the collaboration mechanism for proposing, reviewing, and discussing changes before merge, according to GitHub Docs, checked 10 August 2026.

The workflow in this article mirrors the video: issue, task spec, Docker sandbox, controlled agent run, verification, logs, pull request, human review.

The conclusion is blunt. The guardrails matter before the model choice does.

How should a GitHub issue become a safe task spec?

A GitHub issue should become a safe task spec by narrowing the work before any agent writes code. The spec should define the goal, allowed files, tests, and out-of-scope work.

The issue is the intake form. The task spec is the work order.

That distinction matters because most agent failures start before the model does anything dramatic. The instruction is too broad, the repo boundary is vague, or the acceptance test is implied.

A good spec says what done means. It also says what not to touch.

For example, an issue might say, “Improve onboarding emails.” That is not safe enough for an agent run.

A task spec should turn that into something like: update the subject line helper, add tests for empty names, touch only the mailer and test files, and do not alter templates.

The spec should include these fields:

• Issue link: the original GitHub issue that triggered the run.
• Goal: one concrete outcome, written in plain language.
• Allowed files: paths the agent may edit, or directories with a clear reason.
• Acceptance tests: commands that must pass before review.
• Out of scope: refactors, dependency changes, migrations, or product choices the agent must avoid.
• Rollback note: how to undo the change if the pull request causes trouble.

I prefer this over a clever prompt because it survives tool changes. Claude Code, Codex, OpenCode, or any future agent can consume the same kind of work order.

The spec also gives the reviewer a way to judge scope. If the pull request edits files outside the allowed list, the issue is not whether the code is smart. The run broke the boundary.

This is where the factory starts to differ from a demo. A demo asks, “Can the model code?” A factory asks, “Was the work authorised, bounded, and testable?”

Why does each agent run need a Docker sandbox?

Each agent run needs a Docker sandbox so the coding work happens in an isolated, disposable workspace. The sandbox limits damage, pins dependencies, and keeps failed runs off the developer machine.

Docker is a container platform that runs applications with their required files in isolated processes. Docker Docs says a container is an isolated process with the files it needs, checked 10 August 2026.

Docker Docs also says a container process created with docker run has its own file system, networking, and process tree separate from the host, checked 10 August 2026.

That matters for AI coding agents because they do not just write text. They inspect files, install packages, run tests, and execute commands.

If that happens on a normal development machine, a bad run can pollute caches, upgrade tools, change generated files, or leave hidden state behind.

A Docker sandbox does not make an unsafe task safe by magic. It gives the workflow a blast shield.

The useful pattern is simple. Clone the repository into a fresh workspace. Build from a pinned image. Mount only the files the run needs. Inject only short-lived credentials. Destroy the container when the run ends.

Dependency pinning matters because reproducibility is part of review. If the agent passes tests only because a global package on my laptop happened to exist, the evidence is weak.

Credential limits matter even more. The agent does not need the keys to the business. It needs the minimum token required to read the repo, create a branch, and open a pull request if verification passes.

Here is the comparison I care about. A CLI-first tutorial optimises for starting fast; a sandboxed factory optimises for repeatable, reviewable runs.

Area	CLI-first demo	Sandboxed factory
Workspace	Developer machine	Disposable container
Dependencies	Whatever is installed	Pinned image and lockfiles
Credentials	Often broad local access	Minimum token per run
Failure cleanup	Manual cleanup	Destroy the workspace
Reviewer evidence	Patch only	Patch, logs, tests, risks

The sandbox is not just a convenience layer. It is the operational boundary that lets me run agents repeatedly without turning my machine into the memory of every failed attempt.

What role should the coding agent play in the pipeline?

The coding agent should be a worker inside a controlled pipeline, not an autonomous teammate with unrestricted repository access. The system owns the boundaries; the agent performs the task.

This is a practical distinction, not a philosophical one. If the agent is a worker, the pipeline can replace the worker without redesigning the workflow.

The worker receives the task spec, inspects the allowed part of the codebase, proposes edits, runs the prescribed checks, and records what happened.

That worker should not widen scope, upgrade dependencies, rewrite architecture, or ship a product decision because the local context felt messy.

Those moves may be valid, but they belong in a new issue or a human discussion. They do not belong inside a narrow run.

I have learned to treat broad agent initiative as risk until proven otherwise. The more an agent improvises, the harder the reviewer must work to separate useful code from accidental product change.

The control plane can be a script, a Makefile target, a GitHub Actions workflow, or a small internal service. The important point is ownership.

GitHub Actions is GitHub’s automation platform for build, test, and deployment pipelines, according to GitHub Docs, checked 10 August 2026.

That makes it a natural place to run verification or enforce gates, even if the coding agent itself runs elsewhere.

The pattern is also tool-neutral. One month the worker might be Claude Code, an AI coding CLI from Anthropic. Another month it might be Codex, OpenCode, or a hosted agent.

If the factory is built around specs, containers, tests, and logs, changing the worker is a procurement and integration problem. It is not a safety redesign.

What verification should happen before a pull request opens?

Verification should run before a pull request opens, not after a reviewer spends attention on it. Formatting, linting, unit tests, relevant integration tests, and a captured log should gate the run.

This is where many examples stop too early. They show a patch and treat the pull request as the finish line.

In a real workflow, the pull request is the handoff. The agent should earn that handoff first.

The minimum verification set depends on the repo, but the factory should define it in advance. The agent should not invent the quality bar during the run.

For a small application, the pre-PR gate might run:

• formatter or style checker
• linter
• unit test suite
• relevant integration tests
• type check, if the project uses one
• security or dependency check, if the changed area justifies it

The log matters as much as the pass or fail label. A reviewer needs to know what ran, what passed, what failed, and what was skipped.

A skipped test is not automatically a failure. It is a problem only when the reason is hidden.

For example, an integration test might need a paid third-party service. The run can mark that as skipped if the pull request clearly says why and names the manual check needed.

GitHub Actions workflows can build and test every pull request, according to GitHub Docs, checked 10 August 2026. That is useful, but it should not be the first time the agent learns the code is broken.

The agent should run local or sandbox checks first. The CI system then becomes an independent confirmation, not the main debugging loop.

When verification fails, the factory should stop or retry under rules. It should not open a pull request that hides the failure under a cheerful summary.

Why log cost and activity for every agent run?

Cost and activity logging make every agent run reviewable. The team should see which issue ran, which tool and model were used, how long it took, which commands executed, and where the agent stopped.

This is not about collecting vanity metrics. It is about being able to answer, “What happened here?” without replaying the whole session from memory.

I write build logs from real workflows because the useful part is rarely the polished end state. The useful part is what was wired up, what cost attention, and what broke.

For an AI coding agent workflow, the run log should be boring and consistent. Boring logs are good logs.

A practical activity log should capture:

• issue ID and branch name
• task spec version
• agent tool and model name
• start time, end time, and elapsed time
• commands executed in the sandbox
• files changed
• verification commands and results
• estimated or actual run cost, where the provider exposes it
• stop reason, such as completed, failed tests, permission denied, or human intervention needed

Cost logging needs care. Model providers expose prices and usage differently, and task cost depends on tokens, retries, tool calls, and failed attempts.

That is why I would avoid broad claims like “this model is cheaper for coding” unless the run data proves it for the actual workflow.

The important first step is traceability. If one agent tool produces useful work but burns three retries per issue, the log will show the operating cost.

Activity logging also protects the agent. When a run fails honestly at a permission boundary, the log proves the boundary worked.

Without that record, a failed run becomes a vague complaint. With it, the team can fix the spec, the sandbox, the test command, or the credential scope.

What should an AI-generated pull request include?

An AI-generated pull request should include the task spec, a concise change summary, verification evidence, known risks, and rollback notes. The reviewer should not have to reconstruct the run.

A pull request is a review package, not just a diff.

GitHub Docs describes pull requests as a place to propose changes and collaborate before merging, checked 10 August 2026. The AI-generated version should make that collaboration easier, not noisier.

The best pull request body is short, structured, and honest. It should not read like a victory lap.

I would use this shape:

• Original task spec: pasted or linked, with the issue link.
• Change summary: two to five bullets explaining what changed.
• Verification evidence: commands run, status, and log link.
• Known risks: untested paths, assumptions, or edge cases.
• Rollback notes: revert command, feature flag, or file-level undo path.
• Human review focus: the specific judgement the reviewer should apply.

The rollback note is often missing. It should not be.

If the change is wrong, the reviewer needs a fast path back. That might be a normal revert, a config toggle, or a reminder that a generated migration must not be rolled back casually.

Known risks are equally important. A pull request that says “all tests passed” but hides a skipped integration check is wasting reviewer time.

The agent should be allowed to say, “I completed the bounded task, but I did not verify payment-provider behaviour because credentials were not available.” That is useful evidence.

A human can then decide whether to request another test, run a manual check, or reject the change.

Why is human review still the final gate?

Human review remains the final gate because software-factory automation can draft code and run tests, but humans still own judgement. Tests do not decide whether the change should merge.

This is the part I would not delegate away. The factory can reduce reviewer workload, but it cannot remove accountability.

Humans still own product judgement. A passing change can still solve the wrong problem.

Security review also stays human. A test suite may not catch a permissions mistake, a data leak, or an unsafe dependency pattern.

Maintainability stays human too. An agent can make a clever patch that future work will hate.

Humans also own the merge decision. That is where the business context enters the software process.

The point of the factory is not to make review ceremonial. The point is to make review faster and sharper.

When the pull request carries a task spec, diff, test evidence, risk list, and rollback note, the reviewer can focus on judgement instead of archaeology.

That is the version of AI coding I trust more: less theatre, more paper trail.

Why does model choice matter less than guardrail quality?

Model choice matters less than guardrail quality because the durable assets are specs, sandboxes, test gates, logs, rollback paths, and review habits. Those assets survive tool changes.

Models still matter. A better model can inspect code faster, follow instructions more reliably, and recover from test failures with less hand-holding.

But a stronger model inside a weak workflow is still a weak workflow.

If the task is vague, the credentials are broad, the workspace is dirty, the tests are optional, and the pull request hides risk, model choice is not the main problem.

The safer bet is to make the factory stricter before making the model more powerful.

That means the same issue-to-PR control plane should work across agent tools. Swap the worker, keep the work order.

Here is the operating principle I would use: let models compete inside the same constraints, not by escaping them.

If one tool finishes faster, logs better, or handles failed tests cleanly, the factory will show it. If another tool needs too much human rescue, the factory will show that too.

The durable way to use AI coding agents is to build an issue-to-PR factory where sandboxes, specs, tests, logs, and human review constrain the agent before model choice becomes the deciding factor.

That is the pull request workflow I want: narrow before code, isolated during work, verified before handoff, logged for review, and merged only by a human.

FAQ

Can I run this workflow without Docker?

Yes, but Docker makes the workflow easier to reset and audit. Without a container, you need another way to isolate files, pin tools, limit credentials, and destroy failed state.

Should the agent be allowed to edit files outside the spec?

No, not inside the same run. If the agent finds a real reason to widen scope, the safe move is to stop, record the finding, and create a new issue or revised task spec.

Does this replace continuous integration?

No. Sandbox verification happens before the pull request opens, while continuous integration confirms the change in the repository’s normal review system. Both gates serve different purposes.

Which AI coding agent should I start with?

Start with the tool your team can constrain, log, and review most easily. A powerful model with weak boundaries is less useful than a good-enough model inside a strong factory.

About Kurt Stockhausen

Kurt Stockhausen runs a business and uses AI agents to build the systems that operate it. His articles are build logs from real workflows: what was wired up, what cost effort, and what broke.

Kurt is not a developer by trade. He treats AI coding tools as a means to run the business better, with human review, operational evidence, and practical judgement kept in the loop.