Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

chore(ci): reject idle checkouts behind change gates (#126949)

Paul D'Ambra5bdc4a4e2098
diff --git a/tools/hogli-commands/hogli_commands/tests/test_workflow_checkout_gating.py b/tools/hogli-commands/hogli_commands/tests/test_workflow_checkout_gating.py
new file mode 100644
index 000000000000..507ac097d497
--- /dev/null
+++ b/tools/hogli-commands/hogli_commands/tests/test_workflow_checkout_gating.py
@@ -0,0 +1,118 @@
+from pathlib import Path
+
+import pytest
+
+import yaml
+from hogli_commands.workflow_lint.checks.checkout_work_gate import CheckoutWorkGateCheck
+from hogli_commands.workflow_lint.model import read_workflows
+
+
+ ("checkout", "work", "job_options", "expected"),
+ [
+ pytest.param(
+ {}, [{"run": "check", "if": "needs.changes.outputs.files == 'true'"}], {}, True, id="idle-checkout"
+ ),
+ pytest.param(
+ {},
+ [
+ {"uses": "example/check@v1", "if": "needs.changes.outputs.files == 'true'"},
+ {"run": "check", "if": "${{ needs.changes.outputs.files=='true' }}"},
+ ],
+ {},
+ True,
+ id="shared-gate",
+ ),
+ pytest.param(
+ {"if": "needs.changes.outputs.files == 'true'"},
+ [{"run": "check", "if": "needs.changes.outputs.files == 'true'"}],
+ {},
+ False,
+ id="gated-checkout",
+ ),
+ pytest.param({}, [{"run": "check"}], {}, False, id="unconditional-work"),
+ pytest.param({}, [], {}, False, id="checkout-only"),
+ pytest.param(
+ {},
+ [{"run": "setup"}, {"run": "check", "if": "needs.changes.outputs.files == 'true'"}],
+ {},
+ False,
+ id="unconditional-setup",
+ ),
+ pytest.param(
+ {},
+ [
+ {"run": "check", "if": "needs.changes.outputs.files == 'true'"},
+ {"run": "check-other", "if": "needs.changes.outputs.other == 'true'"},
+ ],
+ {},
+ False,
+ id="different-gates",
+ ),
+ pytest.param(
+ {},
+ [{"run": "check", "if": "steps.changes.outputs.files == 'true'"}],
+ {},
+ False,
+ id="checkout-dependent-gate",
+ ),
+ pytest.param(
+ {"id": "checkout"},
+ [{"run": "check", "if": "needs.changes.outputs.files == 'true'"}],
+ {"outputs": {"sha": "${{ steps.checkout.outputs.commit }}"}},
+ False,
+ id="checkout-output",
+ ),
+ pytest.param(
+ {},
+ [{"run": "check", "if": "needs.changes.outputs.files == 'true'"}],
+ {"if": "${{ needs.changes.outputs.files=='true' }}"},
+ False,
+ id="job-already-gated",
+ ),
+ pytest.param(
+ {},
+ [{"run": "check", "if": "needs.changes.outputs.files == 'true'"}],
+ {"if": "needs.changes.outputs.files == 'true' && github.event_name == 'pull_request'"},
+ False,
+ id="stronger-job-gate",
+ ),
+ pytest.param(
+ {},
+ [{"run": "check", "if": "needs.changes.outputs.files == 'true' && hashFiles('input') != ''"}],
+ {},
+ False,
+ id="checkout-dependent-expression",
+ ),
+ ],
+)
+def test_checkout_work_gate(
+ tmp_path: Path,
+ checkout: dict[str, object],
+ work: list[dict[str, object]],
+ job_options: dict[str, object],
+ expected: bool,
+) -> None:
+ workflow = {
+ "name": "Checks",
+ "on": ["pull_request"],
+ "jobs": {
+ "lint": {
+ "runs-on": "ubuntu-24.04",
+ "timeout-minutes": 5,
+ "steps": [{"uses": "actions/checkout@v6", **checkout}, *work],
+ **job_options,
+ }
+ },
+ }
+ (tmp_path / "checks.yml").write_text(yaml.safe_dump(workflow))
+
+ result = CheckoutWorkGateCheck().run(list(read_workflows(tmp_path)))
+
+ assert len(result.issues) == int(expected)
+ if expected:
+ issue = result.issues[0]
+ assert issue.workflow == "checks.yml"
+ assert issue.job == "lint"
+ assert issue.step == "step[0]"
+ assert "needs.changes.outputs.files" in issue.message
diff --git a/tools/hogli-commands/hogli_commands/workflow_lint/checks/__init__.py b/tools/hogli-commands/hogli_commands/workflow_lint/checks/__init__.py
index 0f4b7dd2cb7d..f36109b2b590 100644
--- a/tools/hogli-commands/hogli_commands/workflow_lint/checks/__init__.py
+++ b/tools/hogli-commands/hogli_commands/workflow_lint/checks/__init__.py
@@ -14,6 +14,7 @@ from __future__ import annotations
from ..check import WorkflowCheck
from .cache_writes import CacheWriteGateCheck
from .checkout_full_depth import CheckoutFullDepthCheck
+from .checkout_work_gate import CheckoutWorkGateCheck
from .dorny_negation import DornyNegationCheck
from .job_timeouts import JobTimeoutsCheck
from .mcp_filter_coverage import McpFilterCoverageCheck
@@ -42,6 +43,7 @@ CHECKS: list[WorkflowCheck] = [
ShellSplitActionArgsCheck(),
StorybookStaticDirsCoverageCheck(),
PausedPublicImagePullsCheck(),
+ CheckoutWorkGateCheck(),
]
diff --git a/tools/hogli-commands/hogli_commands/workflow_lint/checks/checkout_work_gate.py b/tools/hogli-commands/hogli_commands/workflow_lint/checks/checkout_work_gate.py
new file mode 100644
index 000000000000..e8dac74eb29a
--- /dev/null
+++ b/tools/hogli-commands/hogli_commands/workflow_lint/checks/checkout_work_gate.py
@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import re
+
+from ..check import CheckResult, Issue, WorkflowCheck
+from ..model import Job, Workflow
+
+CHANGE_GATE_RE = re.compile(r"(needs\.[\w-]+\.outputs\.[\w-]+)\s*==\s*'true'")
+
+
+def _change_gate(value: object) -> str | None:
+ if not isinstance(value, str):
+ return None
+ condition = value.strip()
+ if condition.startswith("${{") and condition.endswith("}}"):
+ condition = condition[3:-2].strip()
+ match = CHANGE_GATE_RE.fullmatch(condition)
+ return match[1] if match else None
+
+
+def _missing_checkout_gate(job: Job) -> str | None:
+ if len(job.steps) < 2 or job.raw.get("outputs") or job.raw.get("if") is not None:
+ return None
+ checkout, *work = job.steps
+ if not (checkout.uses or "").lower().startswith("actions/checkout@") or checkout.raw.get("if") is not None:
+ return None
+ gate = _change_gate(work[0].raw.get("if"))
+ if gate is None:
+ return None
+ return gate if all(_change_gate(step.raw.get("if")) == gate for step in work) else None
+
+
+class CheckoutWorkGateCheck(WorkflowCheck):
+ id = "WF018-checkout-work-gate"
+ label = "checkout work gate"
+ description = "checkouts skip when all later steps share a change-output gate"
+
+ @property
+ def fix_hint(self) -> str:
+ return "Apply the shared change-output condition to checkout. Keep required-check jobs running when no files match."
+
+ def run(self, workflows: list[Workflow]) -> CheckResult:
+ result = CheckResult()
+ for workflow in workflows:
+ for job in workflow.jobs:
+ gate = _missing_checkout_gate(job)
+ if gate is not None:
+ result.issues.append(
+ Issue(
+ workflow=workflow.path.name,
+ file=str(workflow.path),
+ job=job.name,
+ step=job.steps[0].ref,
+ message=f"Checkout runs when all later steps skip; add if: {gate} == 'true' to checkout.",
+ )
+ )
+ return result