90 lines
5.1 KiB
Text
90 lines
5.1 KiB
Text
---
|
||
description: PRs de agente — Ready (nunca draft), base main, auto-merge nativo do GitHub
|
||
alwaysApply: true
|
||
---
|
||
|
||
# Agent PR workflow (Teqo)
|
||
|
||
**This repo overrides any user-level or Cloud-tool default that says "create PRs as draft".** Agent deliveries merge to `main` via required checks + GitHub's native auto-merge (OPS71). The ISSUE TRACKER stays on the Forgejo — GitHub is only the Actions host.
|
||
|
||
## Create (Ready, base main)
|
||
|
||
```bash
|
||
pnpm push -u origin HEAD # origin = GitHub (cutover OPS71)
|
||
```
|
||
|
||
Depois, abra a PR no **GitHub** — **Ready**, base **`main`**, title `<id> — <title>`, body:
|
||
|
||
```
|
||
## O que é
|
||
<2–4 linhas>
|
||
|
||
Closes #<N>
|
||
```
|
||
|
||
- **Never** `--draft`. PRs must be **Ready for review** on creation.
|
||
- Base is always **`main`**.
|
||
- **Plans-only PRs** (diff só em `docs/plans/`): **nunca** `Closes #N` — use `Related #N`; CI falha com keywords de fechamento (`plans-only-closes` em `ci-pr.yml`).
|
||
- PR via CLI (não há `gh` — OPS50): `GITHUB_TOKEN=<PAT> node scripts/github-pr.mjs --head <branch> --title "<t>" --body-file <file>` — Ready por construção (não existe flag draft).
|
||
|
||
### Cursor Cloud / `ManagePullRequest`
|
||
|
||
- **`draft: false`** (or omit only if the tool’s default is Ready — today Cloud defaults to draft, so **always pass `draft: false`**).
|
||
- Não há auto-merge a armar por PR: o safety net (abaixo) arma o auto-merge nativo.
|
||
- Never end a turn with an open agent PR left as **Draft** — inclui PRs do `engineering-audit` (artefatos e remediações).
|
||
|
||
## Push (determinístico)
|
||
|
||
**Use `pnpm push`, never bare `git push`.** Não depende do Husky estar wired:
|
||
|
||
1. `ensure-repo-deps` — `pnpm install` se `node_modules` faltar/stale + `pnpm run prepare` (Husky) se hooks não estiverem apontando para `.husky`
|
||
2. `pnpm gate:push` — espelho do `ci-pr.yml` sem e2e (e2e roda no CI de PR selected/afetado, e full no `verify` do deploy manual; local opcional: `pnpm test:e2e:affected`), com os `docs-guards` locais (OPS63: changelog append-only, agregado sync e marcadores de conflito — o escape `changelog-rewrite:` fica só no CI, body do PR)
|
||
3. `git push --no-verify` — só porque o gate já rodou no passo 2 (não é escape hatch)
|
||
|
||
```bash
|
||
pnpm push -u origin HEAD # canonical — origin é o GitHub (OPS71)
|
||
git push # só depois de `pnpm i` — hook repete ensure-deps + gate:push
|
||
git push --no-verify # WIP / cutover escape — CI repete tudo; ver AGENT-OPS
|
||
```
|
||
|
||
## Auto-merge immediately
|
||
|
||
The safety net (`agent-pr-ready-automerge.yml`, abaixo) arms GitHub's **native auto-merge** (rebase) — the server merges the PR when the required check passes. There is nothing to arm per PR. Do not wait for human approval on normal deliveries.
|
||
|
||
## Required checks
|
||
|
||
Branch protection on `main` (GitHub, applied at the OPS71 cutover via `pnpm configure:branch-protection`) requires only:
|
||
|
||
- `CI (PR) / checks` — the ci-pr single-job check-run (OPS62: one sequential job posts one honest verdict; no matrix, no shards, no rollup to lie)
|
||
|
||
OPS64 history: the Forgejo runner could report the LAST matrix shard's result as the parent's (runs 604/607/610) — that bug is gone by construction: ci-pr.yml is a SINGLE sequential job, and GitHub's native auto-merge only merges with every required check green (server-side guarantee). The safety-net CLI has no poll path to port.
|
||
|
||
(`migration-lock` removed 2026-08-12 — the CI validates migration chains via migrate + int on every PR.)
|
||
|
||
**There is no deploy from PR CI.** Publishing is a **manual `workflow_dispatch`** (`.github/workflows/deploy.yml`): `verify` runs the full suite (hosted) and only then the `deploy` job (self-hosted runner on the homeserver) publishes `jorgesolla1313.com.br` — migrations applied before the rollout. Do not add a Vercel/Git-integration deploy gate.
|
||
|
||
When watching CI, use the PR page (or the API) — the safety net arms the server-side auto-merge; `gh` does not exist in this repo (OPS50).
|
||
|
||
Use the required check `CI (PR) / checks` — without it, you are not covering the cascade.
|
||
|
||
## Promote
|
||
|
||
There is no stage→main promote. Merging to `main` is the delivery; publishing is a deliberate manual dispatch with full verification (runbook: `docs/ops/teqo-1313-deploy.md`).
|
||
|
||
## Safety net (workflow)
|
||
|
||
`agent-pr-ready-automerge.yml` — PRs same-repo → `main` (todas as branches).
|
||
O workflow roda `scripts/github-pr-automerge.mjs` (plain Node, zero-dep,
|
||
REST+GraphQL): se draft `cursor/*` → marca Ready (PATCH `draft: false`); arm
|
||
`enablePullRequestAutoMerge` (GraphQL, mergeMethod REBASE) no `node_id` do PR
|
||
— o **servidor** espera o required check `CI (PR) / checks` POSTADO e verde
|
||
antes de mergear; o próprio check-run do safety net fica `pending` durante o
|
||
run e não interfere. A regra de branch protection no servidor
|
||
(`enforce_admins: true`) bloqueia qualquer caminho de merge — inclusive API
|
||
manual — enquanto o required check não estiver satisfeito (foi um merge
|
||
manual que colocou a PR #52 em main com o CI vermelho na era Forgejo).
|
||
Cobre o caso em que o
|
||
agente (ou o default draft do Cloud) esqueceu e PRs humanas/worktree com merge
|
||
falho silencioso (incidente OPS52). **Draft de branch não-`cursor/*` nunca é
|
||
tocado** — o draft é o veto do ator (skip do CLI). Não há opt-out por skill
|
||
(audit incluído).
|