PRs con GitHub CLI para coding agents: nunca push a main

Un coding agent que hace git push origin main no es “rápido”: es un incidente. El cierre correcto es un pull request. GitHub CLI (gh) está hecho para eso: gh pr create imprime la URL si sale bien. En modo no interactivo hay que saltar todos los prompts.

Esto no sustituye sandboxing ni el ranking de mejores agentes de código. Es el borde GitHub: cómo el agente entrega trabajo. El curso instalar un agente cubre el loop local.

El contrato en cuatro comandos

git checkout -b agent/fix-login   # o git worktree add -b ...
git add -p && git commit
git push -u origin HEAD
gh pr create --head agent/fix-login \
  --title "fix: login timeout" \
  --body "Reproduce, causa, test."

--head evita que gh pregunte si forkea o a qué remote empuja. --title y --body evitan el editor. El manual lo dice: si no los pasas, hay prompt. --fill usa el mensaje del commit; útil si el agente ya escribió un commit decente. Si mezclas --fill con --title, gana el flag explícito.

--base apunta a la rama destino (main por default del repo, o gh-merge-base en git config). Un agente no adivina develop: léelo de gh repo view --json defaultBranchRef.

Flags que el agente debe conocer

Flag	Uso	Si lo omites
--title / --body	No interactivo	Prompt o editor
--head	Rama ya pusheada	Pregunta remote/fork
--base	Destino	Default del repo
--draft	CI primero, review después	PR “listo”
--dry-run	Ver el payload	Crea de verdad
--no-maintainer-edit	Forks externos	Maintainers pueden pushear tu rama
--reviewer	Pedir review	Nadie se entera
-F -	Body por stdin	Heredoc frágil en el parser del agente

Fixes #123 / Closes #123 en el body cierra el issue al merge. El agente no debe poner Fixes si el PR es parcial.

Lo que el agente no hace

• git push origin main / --force / --force-with-lease “porque el remoto está sucio”.
• gh pr merge salvo que un humano lo pida. Este loop de guías, por ejemplo, nunca mergea.
• gh pr create sin push previo: el CLI ofrece pushear; en CI/headless eso cuelga o crea un fork vacío (solo default branch). --head salta ese camino.
• Abrir el browser (-w). No hay humano sentado.

Auth: gh auth status debe ser verde antes del agente. El token vive en el entorno del operador, no en el prompt. Si gh pide login, el agente se detiene.

Receta anti-caos (varios agentes)

Cada agente: rama agent/<slug> + --head de esa rama. Dos PRs pueden tocar el mismo test de conteos: el segundo merge falla. Eso se arregla rebase después, no con force al primero.

Si gh pr create dice “must first push”: el --head apunta a una rama que no existe en origin. git push -u origin HEAD y reintenta. Si dice “No commits between”: estás en main o tu rama no divergió.

gh pr list --head agent/fix-login evita duplicar el mismo PR. Si ya hay uno abierto, gh pr edit + push de commits nuevos. No abras el #2.

Checklist

• No estás en main.
• git status limpio (o el commit es consciente).
• Push de tu rama.
• gh pr create --title --body --head (sin -w).
• La URL del PR es el artifact. Sin URL, no terminó.
• Cero merge, cero force.

gh pr view --json url,title,state confirma que el PR existe antes de reportar “listo”. Un create que imprimió URL y luego un push --force a la misma rama reescribe lo que el reviewer ya vio: eso es el mismo incidente con más pasos. Commits nuevos, push normal.

Si el default branch está checked out en otro worktree, gh pr merge puede fallar por eso; da igual: el agente no mergea.

FAQ

¿--fill basta? Sí si el commit subject es el título que quieres en GitHub. Si el agente hace 6 commits “wip”, no.

¿Draft siempre? Sí cuando CI tarda o el humano no está. gh pr ready después.

¿El agente asigna reviewers? Solo si la org lo documenta. --reviewer @me es inútil.

¿gh pr create desde un worktree? Sí: el cwd del worktree fija la rama. --head igual, por si el cwd miente.

Verificado 2026-09-03 contra gh pr create --help y https://cli.github.com/manual/gh_pr_create.