pr-pipeline: run Refine before review, triggered by events and file extensions

Abierto
  • ¿Algo no está bien?
#13,717 13 comentarios 0 reacciones 1 asignado Ver en GitHub

Los mantenedores suelen responder en 1 día

@kyle-sexton ya está trabajando en esto.

Desde el 6/11/2026.

Evaluación

Este issue todavía no se ha evaluado.

Descripción

host-run priority: medium status: needs-decision work-class: structural

Refs: #8485

Problem

Review sees code that has not been tidied yet. Review lanes start on opened, synchronize and ready_for_review (.github/workflows/pr-review-hosted.yml:48). fix-docs, the one tidy pass that runs after a PR opens, waits for a cron at minutes 9 and 39 (.github/workflows/pr-unblock-dispatch.yml:61). So the first review of every PR judges the head before tidying, and a fix-docs push restarts both reviews. The owner's direction (2026-11-06): tidying runs before code and security review, on every PR whose changed files qualify by extension, as passes in a Refine stage, event-driven, with clear signals that agents and people read the same way.

Decision

Owner, 2026-11-06, "go w/ recommended" on lane 3's Q6 (a):

  • Ready starts this repository's pipeline: Refine first, then review. Draft and save point keep their meanings.
  • Refine is one pr-refine workflow that always runs, dispatched by an event (no cron). Its first job matches the PR's changed files to each pass's applies-when.paths extension globs in docs/conventions/pr-pipeline.yaml. Passes on disjoint extensions run in parallel; overlapping ones run in their configured order. A PR that matches no pass completes Refine in seconds. There is no workflow-level path filter, because a skipped workflow leaves its checks Pending (https://docs.github.com/actions/managing-workflow-runs/skipping-workflow-runs).
  • Review starts on workflow_run of pr-refine completing (https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows). A Refine run that pushed a patch tells review to skip that head, and the push starts Refine again on the new head.
  • Signals are native: draft and ready state, workflow completion, and one check per pass (refine / <pass>). No label gates anything.
  • Repository-specific wiring stays in .github/ and docs/conventions/. Shipped plugins stay team-, user- and repo-agnostic: create.md §2.4.3 keeps its generic states.
  • Adding a pass is a config entry (an activity with stage: refine, its globs, its order).
  • Each pass logs its name, files matched, patch yes or no, and duration, so passes can be measured and compared.

Later owner decisions, 2026-11-06 (each comment quotes the owner):

  • Q8 (issuecomment-6687918323): review waits for Refine and takes the PR and head from the Refine run; pr-review-cli.yml gained the inputs for a workflow_run caller.
  • Q11 and Q13 (issuecomment-6692723687, issuecomment-6694392754): fix-docs is on for every PR whose tidy did not run inside its own run; a resolve-issue lane PR that tidied in its run is skipped. Shipped in #13818 (ADR 0089).
  • Q12 (issuecomment-6694392754): a pull_request_target dispatcher starts Refine under four tested invariants: main's code only, no head-controlled text in run:, actions: write and contents: read only, no App token or secret beyond GITHUB_TOKEN. The cron stays as a backstop until one event-started Refine is seen reaching review. The azure-iac broker rule for it is melodic-software/azure-iac#116.
  • Q16 (issuecomment-6695832454): an explicit Actions event policy allows pull_request_target for the named workflows only. This repository's policy 10299 already covers pr-merge.yml; the dispatcher's path joins it when its trigger ships.
  • Lane 3, on evidence: resolve-issue lane-branch PRs keep their pull_request review start; every other PR is reviewed after Refine.

Done when

Phase A:

  • Dependency: melodic-software/ci-workflows#999 merged (pr-review-cli.yml accepts pr-number, head-sha, base-sha and event-action from a workflow_run caller).
  • Dependency: melodic-software/standards#953 merged and its runner-policy sync landed here (#13742) (.github/standards/runner-policy/policy.json allows the four inputs).
  • The trusted dispatcher pr-unblock-dispatch.yml gains a pull_request_target trigger that dispatches Refine, runs main's code, and never checks out head code, and check-trusted-trigger accepts that event, with one test per Q12 invariant that fails when the invariant is weakened. Depends on melodic-software/azure-iac#116 deployed.
  • Policy 10299 includes the dispatcher's workflow path.
  • A ready PR, and each push to one, starts pr-refine through an event (the dispatch path is covered by a test). The cron dispatch of fix-docs is removed once one event-started Refine is seen reaching review.
  • pr-refine always runs, plans its passes from pr-pipeline.yaml applies-when.paths, and runs fix-docs as its first pass. A PR with no qualifying files completes with no model turn (test).
  • The AI review workflows start on workflow_run of pr-refine completing with any conclusion, passing the PR number and head from that Refine run to pr-review-cli.yml's new inputs (success, failure, cancelled, timed out), and skip only a head that Refine moved, a draft, or a hold (tests, including a positive control).
  • Review is never stranded by Refine: every Refine job has a timeout-minutes; a failed or refused dispatch of Refine still starts review; and a Refine failure logs refine-failed and is counted the way other lane holds are, so a lasting failure reaches a person (tests for a failed, a timed-out and a never-dispatched Refine).
  • workflow_run stays within GitHub's three-level chain limit (.github chain listed in the PR body).
  • Each pass emits one record with its name, files matched, patch outcome and duration (test).
  • docs/conventions/pr-pipeline/README.md states the stage order and what each signal means. No shipped plugin file gains repo-specific wording (git diff --stat shows no plugins/ change, or only generic config points).
  • All .github node tests pass.

Later phases (not this issue's done-when): a /simplify pass on code extensions as a config entry, and moving resolve-issue's in-run tidy steps into Refine, each with before-and-after numbers.

Lenguaje dominante
Shell
Estrellas
22
Forks
2
Merge medio
1 h 13 min
PR fusionados (30 d)
954

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de melodic-software/claude-code-plugins

Todos los issues de melodic-software/claude-code-plugins

Issues similares

Más issues de Shell/Bash

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.