fix(strict-lane)!: paths 필터 trigger로만 도는 workflow는 단계 실행으로 세지 않는다

문제: verifyStrictLaneStages의 workflow 판독기는 trigger 이름과
types만 본다. paths·paths-ignore 필터가 붙은 pull_request·push로만
시작하는 workflow의 `./gradlew :ci`도 실행으로 센다. 그런 workflow는
필터 밖 변경에서 돌지 않는데, 실패 메시지와 업그레이드 안내 B-36은
"매 push·pull request·schedule에 도는 workflow에서 단계를 돌리라"고
약속한다(리뷰 RR7-05-01).

고른 방법: 소유자 결정(2026-11-06, docs/work/reference/decisions.md
"경로 필터 workflow와 단계 검사")대로, change trigger에 paths나
paths-ignore가 있으면 그 trigger로는 세지 않는다. 필터 없는 change
trigger가 하나라도 있으면 지금처럼 센다. 세지 않는 이유는 "돌지 않을
수 있음" 칸이고, 메시지가 어느 trigger의 어떤 필터인지 적는다
(예: "push (paths-ignore)"). trigger마다 types와 경로 필터를 함께
읽도록 Trigger 레코드를 두었다. 실패 메시지(NOT_COUNTED), AGENTS.md,
src/README.md, build-logic/README.md, 업그레이드 안내 B-36을 같은
규칙으로 고쳤다.
버린 대안: 동작은 두고 메시지·B-36의 약속만 고친다 — 소유자가 위
안을 골랐다. branches·tags 필터까지 판정한다 — 결정 범위 밖이라
읽지 않고, Javadoc과 문서에 읽지 않는다고 적었다.

위험·한계: 파생 서비스가 단계 명령을 paths 필터 workflow에만 두었으면
이제 verifyStrictLaneStages --dry-run이 실패한다. 이 repo는 단계 명령이
필터 없는 workflow에 있어 두 빌드 모두 판정이 그대로다. tags와 paths가
함께 있는 push(GitHub은 태그 push에 paths를 보지 않음)도 세지 않는다 —
거짓 실패 쪽이다. 실제 GitHub의 필터 해석은 실행해 보지 않았다.

검증(desktop, 로그 ~/r8-f5-logs/):
- RED: 기준 73d39212에 테스트만 얹음. WorkflowGradleInvocationsTest
  44건 중 1건 실패 — 필터 workflow 셋 모두 uncountedReason=null
  (red-rr7-05-01.log, .xml)
- GREEN: 같은 테스트 rc=0 (green-rr7-05-01.log)
- -p build-logic check javadoc, :verifyStrictLaneStages --dry-run,
  -p optional-platforms :verifyStrictLaneStages --dry-run,
  :ci :verifyDependencyLocks rc=0 (summary.txt)

Refs: docs/reviews/2026-11-03-rereview/round7/05-build-logic-workflow.md RR7-05-01
BREAKING CHANGE: change trigger가 모두 paths·paths-ignore 필터를 단 workflow에서만 단계(:ci 등)를 부르면 verifyStrictLaneStages --dry-run이 실패한다. 단계 명령을 필터 없는 push·pull_request·schedule workflow로 옮긴다(docs/upgrade/2026-11-maturity-review.md B-36).
This commit is contained in:
DongHyeonka
2026-11-07 01:10:30 +09:00
parent 73d39212f5
commit 6cd5e925c1
7 changed files with 177 additions and 43 deletions
+4 -2
View File
@@ -98,8 +98,10 @@ root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을
`&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec`·`set -n` 뒤, 조건부이거나
부른 함수 안의 `exit 0`(인자 없는 `exit`, 값을 모르는 `exit` 포함)·`exec`·`set -n` 뒤, 상태
함수(`always()`·`success()`·`!cancelled()`)가 아닌 `if:` 아래, 요청으로만
시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), 세는 job이 부르지 않는
`workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는 job.
시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), `paths`·`paths-ignore`
필터가 붙은 change trigger로만 시작하는 workflow(그 경로 밖 변경에는 돌지 않는다), 세는 job이
부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는
job.
(3) 실패하면 단계도 실패하지만 검사가 읽지 않는다: `|| exit 1`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른
명령의 인자인 `gradlew`, 따라갈 수 없는 `cd`(`cd "$VAR"`·`cd -`·`pushd`·조건부·서브셸 등) 뒤,
`bash`·`sh`가 아닌 `shell:`, Windows일 수 있는 runner의 기본 셸(`pwsh`). 실패 메시지는 명령마다 이유를
File diff suppressed because one or more lines are too long
+1 -1
View File
@@ -28,7 +28,7 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
| `qualificationCheck` | 전체 기동(system) 레인과 보조 source set Checkstyle을 실행 |
| `integrationCheck` | 선언된 strict integration lane(sample 포함)을 실행. 대부분 container runtime이 필요. 입력이 필요한 lane(Redis topology: `-Predis.topology.mode`, AWS: 보호 자격 증명 env)은 입력이 없으면 빠지고 집계가 그 이유를 출력 |
| `performanceCheck` | 선언된 strict performance lane(부하·종료·pool·자원 상한)을 실행. 실서버·container가 필요. 상한은 매번 단언하고 끄는 속성이 없다(`-Pperformance.assertions.enabled`가 `true`가 아니면 실패, skip된 테스트가 있어도 실패). `integration-main.yml` `performance-check`가 main·nightly에 같은 명령으로 돌림 |
| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 workflow가 실제 실행하는 단계(`ci`·`:sample-portfolio:check`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 각 단계를 workflow가 `--dry-run` 없이 실행하는지 검사. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-v`·`--help` 등)과, 실패해도 단계가 실패하지 않을 수 있거나(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) 돌지 않을 수 있거나(조건부 `exit 0` 뒤, 요청으로만 시작하는 workflow 등) 검사가 읽지 않는(`\|\| exit 1`, `{ }` 안 등) 명령은 실행으로 세지 않는다. 자세한 목록은 `build-logic/README.md`. PR 게이트가 돌림 |
| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 workflow가 실제 실행하는 단계(`ci`·`:sample-portfolio:check`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 각 단계를 workflow가 `--dry-run` 없이 실행하는지 검사. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-v`·`--help` 등)과, 실패해도 단계가 실패하지 않을 수 있거나(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) 돌지 않을 수 있거나(조건부 `exit 0` 뒤, 요청으로만 시작하는 workflow, `paths` 필터로만 시작하는 workflow 등) 검사가 읽지 않는(`\|\| exit 1`, `{ }` 안 등) 명령은 실행으로 세지 않는다. 자세한 목록은 `build-logic/README.md`. PR 게이트가 돌림 |
| `ci` | PR 게이트: 모든 leaf `check`(API surface 검사 포함, 소유자 결정 20) + `architectureCheck` + `qualityCheck` |
| `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + sample web 계약 + sample 전체 기동(`:sample-portfolio:systemTest`) + `verifyPublicPathSnapshot` + 전송·메시징 qualification 레인 + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) |
| `releaseCheck` | tag 전용 검사: `verifyReleaseProvenance` + `verifyPublicPathSnapshot`(`ci`를 다시 돌리지 않음) |
File diff suppressed because one or more lines are too long
@@ -33,7 +33,8 @@ import org.gradle.api.execution.TaskExecutionGraph;
* as a workflow runs it — a lane the command removes with {@code -x} is not covered, matched
* the way Gradle matches it, abbreviations included ({@link TaskSelectors});
* <li>every declared stage is executed by a workflow. Not counted ({@code NOT_COUNTED}; review
* 2026-11-03 RR-06-04, 2026-11-04 RR2-04-04, RR5-02-02, 2026-11-05 RR6-04-01..06): a command
* 2026-11-03 RR-06-04, 2026-11-04 RR2-04-04, RR5-02-02, 2026-11-05 RR6-04-01..06, 2026-11-06
* RR7-05-01): a command
* after which Gradle runs no task ({@code --dry-run}, {@code -v}, {@code --help}, …) or that
* Gradle rejects (a short-option bundle such as {@code -mx}), one for another build, and one
* that does not gate for one of three reasons — its failure may not fail its step, it may not
@@ -66,13 +67,15 @@ public final class StrictLaneStagesPlugin implements Plugin<Project> {
+ " script's last command, after set +e or a trap that exits 0, continue-on-error); one"
+ " that may not run (after ||, inside if/while/for/case or a function, after an exit 0,"
+ " exec or set -n, under an if: other than always()/success()/!cancelled(), in a"
+ " workflow that starts only on a request or a reusable one no counted job calls, in a"
+ " workflow that starts only on a request, or on changes only through a paths or"
+ " paths-ignore filter, or a reusable one no counted job calls, in a"
+ " job that needs a job that may be skipped); and one this check does not read although"
+ " its failure"
+ " would fail the step (|| exit 1, inside { } or ( ), $( ), bash -c, gradlew as"
+ " another command's argument, after a cd it does not follow, a shell other than bash"
+ " or sh, a runner that may be Windows). Run the stage as ./gradlew on a line of its"
+ " own, in a step and job that run on every push, pull request or schedule";
+ " own, in a step and job that run on every push, pull request or schedule, with no"
+ " paths or paths-ignore filter";
@Override
public void apply(Project project) {
@@ -44,7 +44,10 @@ import java.util.regex.Pattern;
* <p><b>When a workflow runs.</b> A workflow counts when one of its triggers is part of the change
* or release flow: {@code push}, {@code pull_request} or {@code pull_request_target} (with a {@code
* types} list, only when it holds {@code opened}, {@code synchronize} or {@code reopened}), {@code
* merge_group}, {@code schedule}, {@code release}. One that starts only on other events — {@code
* merge_group}, {@code schedule}, {@code release} — and has no {@code paths} or {@code
* paths-ignore} filter: a change that touches none of the listed paths, or only ignored ones, does
* not start it (owner decision 2026-11-06, review RR7-05-01). Its {@code branches} and {@code tags}
* filters are not read. One that starts only on other events — {@code
* workflow_dispatch}, {@code repository_dispatch}, {@code issue_comment}, a {@code labeled} pull
* request, {@code workflow_run} and the rest — runs only when someone or something asks (review
* 2026-11-04 RR2-04-04, RR6-04-06). A workflow that starts only on {@code workflow_call} counts
@@ -98,6 +101,8 @@ public final class WorkflowGradleInvocations {
/** The pull-request activity types that come with every new change. */
private static final Set<String> PULL_REQUEST_CHANGE_TYPES =
Set.of("opened", "synchronize", "reopened");
/** The trigger filters that start a workflow only for changes to some files. */
private static final List<String> PATH_FILTERS = List.of("paths", "paths-ignore");
private static final String REUSABLE_WORKFLOWS = "./.github/workflows/";
/**
* Gradle 9.0's command-line options that take a value, by every name it accepts. Probed against
@@ -256,9 +261,19 @@ public final class WorkflowGradleInvocations {
ShellScript.Options shell,
String uncountedReason) {}
/** One workflow file: its name, its lines, its triggers with their {@code types}, its jobs. */
/** One workflow file: its name, its lines, its triggers by event name, its jobs. */
private record Workflow(
String file, List<String> lines, Map<String, List<String>> triggers, Map<String, Job> jobs) {}
String file, List<String> lines, Map<String, Trigger> triggers, Map<String, Job> jobs) {}
/**
* One trigger's filters that decide whether it runs on every change.
*
* @param types its {@code types} list, or {@code null} when it has none
* @param pathFilters which of {@code paths} and {@code paths-ignore} it has
*/
private record Trigger(List<String> types, List<String> pathFilters) {
private static final Trigger UNFILTERED = new Trigger(null, List.of());
}
/** A job: its id, the line of its key, and the column of its own keys (-1 when it has none). */
private record Job(String id, int header, int keyIndent) {}
@@ -476,12 +491,9 @@ public final class WorkflowGradleInvocations {
// ---------------------------------------------------------------------------------------------
// When the workflow runs
/**
* The workflow's triggers, each with its {@code types} list, or {@code null} when it has none;
* empty when no {@code on:} is written.
*/
private static Map<String, List<String>> triggers(List<String> lines) {
Map<String, List<String>> triggers = new LinkedHashMap<>();
/** The workflow's triggers with their filters; empty when no {@code on:} is written. */
private static Map<String, Trigger> triggers(List<String> lines) {
Map<String, Trigger> triggers = new LinkedHashMap<>();
for (int index = 0; index < lines.size(); index++) {
Matcher on = TRIGGER_KEY.matcher(lines.get(index));
if (!on.matches()) {
@@ -494,7 +506,7 @@ public final class WorkflowGradleInvocations {
int colon = entry.indexOf(':');
triggers.put(
stripScalarComment(colon < 0 ? entry : entry.substring(0, colon)),
colon < 0 ? null : flowTypes(entry.substring(colon + 1).trim()));
colon < 0 ? Trigger.UNFILTERED : flowTrigger(entry.substring(colon + 1).trim()));
}
} else if (!inline.isEmpty()) {
String list =
@@ -502,7 +514,7 @@ public final class WorkflowGradleInvocations {
? inline.substring(1, inline.length() - 1)
: inline;
for (String trigger : flowItems(list)) {
triggers.put(trigger, null);
triggers.put(trigger, Trigger.UNFILTERED);
}
} else {
blockTriggers(lines, index, triggers);
@@ -514,7 +526,7 @@ public final class WorkflowGradleInvocations {
/** The triggers of a block {@code on:} at {@code onLine}: a mapping or a list. */
private static void blockTriggers(
List<String> lines, int onLine, Map<String, List<String>> triggers) {
List<String> lines, int onLine, Map<String, Trigger> triggers) {
int childIndent = childIndent(lines, onLine);
for (int next = onLine + 1; next < lines.size(); next++) {
String line = lines.get(next);
@@ -532,35 +544,55 @@ public final class WorkflowGradleInvocations {
boolean item = key.startsWith("-");
key = item ? key.substring(1).trim() : key;
int colon = key.indexOf(':');
List<String> types = null;
Trigger trigger = Trigger.UNFILTERED;
String inlineDetail = colon < 0 ? "" : key.substring(colon + 1).trim();
if (!item && inlineDetail.startsWith("{")) {
types = flowTypes(stripScalarComment(inlineDetail));
trigger = flowTrigger(stripScalarComment(inlineDetail));
} else if (!item && colon >= 0) {
int detailIndent = childIndent(lines, next);
int typesLine =
detailIndent > childIndent ? mappingKey(lines, next + 1, detailIndent, "types") : -1;
types = typesLine < 0 ? null : listValue(lines, typesLine);
if (detailIndent > childIndent) {
int typesLine = mappingKey(lines, next + 1, detailIndent, "types");
List<String> pathFilters = new ArrayList<>();
for (String filter : PATH_FILTERS) {
if (mappingKey(lines, next + 1, detailIndent, filter) >= 0) {
pathFilters.add(filter);
}
}
trigger =
new Trigger(typesLine < 0 ? null : listValue(lines, typesLine), pathFilters);
}
}
triggers.put(stripScalarComment(colon < 0 ? key : key.substring(0, colon)), types);
triggers.put(stripScalarComment(colon < 0 ? key : key.substring(0, colon)), trigger);
}
}
/** The {@code types} of a flow-mapping trigger value such as {@code {types: [created]}}. */
private static List<String> flowTypes(String value) {
/**
* The filters of a flow-mapping trigger value such as {@code {types: [created]}} or {@code
* {paths: [docs/**]}}.
*/
private static Trigger flowTrigger(String value) {
if (!value.startsWith("{") || !value.endsWith("}")) {
return null;
return Trigger.UNFILTERED;
}
List<String> types = null;
List<String> pathFilters = new ArrayList<>();
for (String entry : flowItems(value.substring(1, value.length() - 1))) {
int colon = entry.indexOf(':');
if (colon >= 0 && stripScalarComment(entry.substring(0, colon)).equals("types")) {
String types = entry.substring(colon + 1).trim();
return types.startsWith("[") && types.endsWith("]")
? flowItems(types.substring(1, types.length() - 1))
: List.of(stripScalarComment(types));
if (colon < 0) {
continue;
}
String key = stripScalarComment(entry.substring(0, colon));
String detail = entry.substring(colon + 1).trim();
if (key.equals("types")) {
types =
detail.startsWith("[") && detail.endsWith("]")
? flowItems(detail.substring(1, detail.length() - 1))
: List.of(stripScalarComment(detail));
} else if (PATH_FILTERS.contains(key)) {
pathFilters.add(key);
}
}
return null;
return new Trigger(types, pathFilters);
}
/**
@@ -569,16 +601,27 @@ public final class WorkflowGradleInvocations {
*/
private static String startReason(
Workflow workflow, Map<String, Workflow> workflows, Set<String> visiting) {
Map<String, List<String>> triggers = workflow.triggers();
Map<String, Trigger> triggers = workflow.triggers();
if (triggers.isEmpty()) {
return null;
}
for (Map.Entry<String, List<String>> trigger : triggers.entrySet()) {
if (runsOnChanges(trigger.getKey(), trigger.getValue())) {
Map<String, Trigger> pathFiltered = new LinkedHashMap<>();
for (Map.Entry<String, Trigger> trigger : triggers.entrySet()) {
if (!runsOnChanges(trigger.getKey(), trigger.getValue().types())) {
continue;
}
if (trigger.getValue().pathFilters().isEmpty()) {
return null;
}
pathFiltered.put(trigger.getKey(), trigger.getValue());
}
String described = describe(triggers);
if (!triggers.containsKey("workflow_call") && !pathFiltered.isEmpty()) {
return "its workflow starts on changes only through "
+ describe(pathFiltered)
+ ", which a change that touches none of the listed paths, or only ignored ones, does"
+ " not start, so it may not run";
}
if (!triggers.containsKey("workflow_call")) {
return "its workflow starts only on "
+ described
@@ -626,12 +669,17 @@ public final class WorkflowGradleInvocations {
|| types.stream().anyMatch(PULL_REQUEST_CHANGE_TYPES::contains);
}
private static String describe(Map<String, List<String>> triggers) {
private static String describe(Map<String, Trigger> triggers) {
List<String> described = new ArrayList<>();
triggers.forEach(
(trigger, types) ->
described.add(
types == null ? trigger : trigger + " (types: " + String.join(", ", types) + ")"));
(name, trigger) -> {
List<String> filters = new ArrayList<>();
if (trigger.types() != null) {
filters.add("types: " + String.join(", ", trigger.types()));
}
filters.addAll(trigger.pathFilters());
described.add(filters.isEmpty() ? name : name + " (" + String.join("; ", filters) + ")");
});
return String.join(", ", described);
}
@@ -1283,6 +1283,87 @@ class WorkflowGradleInvocationsTest {
.allSatisfy(invocation -> assertThat(invocation.executes(":ci", "src")).isTrue());
}
@Test
@DisplayName("paths·paths-ignore 필터가 붙은 change trigger로만 시작하는 workflow의 명령은 세지 않는다")
void aWorkflowThatStartsOnChangesOnlyThroughAPathFilterGatesNothing() {
// given
List<String> workflows =
List.of(
"""
on:
pull_request:
paths: ["docs/**"]
push:
branches: [main]
paths:
- "docs/**"
jobs:
main:
steps:
- working-directory: src
run: ./gradlew :ci
""",
"""
on: {push: {paths-ignore: ["docs/**"]}, workflow_dispatch: {}}
jobs:
main:
steps:
- working-directory: src
run: ./gradlew :ci
""",
"""
on:
pull_request: {types: [opened, synchronize], paths: ["src/**"]}
jobs:
main:
steps:
- working-directory: src
run: ./gradlew :ci
""");
// when
List<Invocation> invocations =
workflows.stream().flatMap(workflow -> WorkflowGradleInvocations.read(workflow).stream())
.toList();
// then
assertThat(invocations)
.hasSize(3)
.allSatisfy(invocation -> assertThat(invocation.executes(":ci", "src")).isFalse());
assertThat(invocations).extracting(Invocation::uncountedReason)
.satisfiesExactly(
reason -> assertThat(reason).contains("pull_request (paths)", "push (paths)"),
reason -> assertThat(reason).contains("push (paths-ignore)"),
reason ->
assertThat(reason).contains("pull_request (types: opened, synchronize; paths)"));
}
@Test
@DisplayName("paths 필터가 붙은 trigger 옆에 필터 없는 change trigger가 있으면 그 workflow의 명령은 센다")
void aWorkflowWithAnUnfilteredChangeTriggerBesidesAPathFilterCounts() {
// given
String workflow =
"""
on:
pull_request:
paths: ["docs/**"]
schedule:
- cron: '0 3 * * *'
jobs:
main:
steps:
- working-directory: src
run: ./gradlew :ci
""";
// when
List<Invocation> invocations = WorkflowGradleInvocations.read(workflow);
// then
assertThat(invocations).singleElement().satisfies(
invocation -> assertThat(invocation.executes(":ci", "src")).isTrue());
}
@Test
@DisplayName("workflow_call로만 시작하는 재사용 workflow의 명령은 매 변경에 도는 호출 job이 있을 때만 센다")
void aReusableWorkflowCountsOnlyThroughACallerThatRunsOnEveryChange() {