#!/usr/bin/env python3 """Check the Workspace workflow's pull-request-only cancellation policy. The policy is the top-level `concurrency` block of .github/workflows/workspace.yml. This script reads those fields, requires the documented expression shapes, and checks which group each event would be given. The rest of the workflow is left to diff review, not frozen here. Use --workflow PATH to read a baseline or a deliberately wrong variant without touching this checkout. """ import argparse import re import sys import unittest from pathlib import Path try: # cross-check only; the reader below is what a plain `python3` run needs import yaml except ImportError: yaml = None DEFAULT_WORKFLOW = Path(__file__).resolve().parent.parent / ".github" / "workflows" / "workspace.yml" PULL_REQUEST, PUSH, DISPATCH = "pull_request", "push", "workflow_dispatch" # The two shapes this policy may use. GitHub reads `a && b || c` as "b, or c when a is false"; these # patterns are the whole of that expression language this script understands, so a reworded policy # has to be reworded here too, on purpose. github.ref, never github.head_ref or github.sha. GROUP_SHAPE = re.compile( r"(?P[A-Za-z0-9._-]+)-\$\{\{\s*github\.event_name\s*==\s*'(?P[a-z_]+)'\s*" r"&&\s*github\.ref\s*\|\|\s*github\.run_id\s*\}\}" ) CANCEL_SHAPE = re.compile(r"\$\{\{\s*github\.event_name\s*==\s*'(?P[a-z_]+)'\s*\}\}") def read_concurrency(text): """The top-level `concurrency` mapping. A deliberately limited reader: two-space fields.""" lines = text.splitlines() starts = [index for index, line in enumerate(lines) if line.startswith("concurrency:")] if len(starts) != 1: raise AssertionError(f"expected one top-level concurrency block, found {len(starts)}") header = lines[starts[0]].partition("#")[0].strip() if header != "concurrency:": # `concurrency: |` and `concurrency: some-string` are scalars, not a mapping. Reading the # lines under one as fields would let a workflow that is not this policy pass every check. raise AssertionError(f"concurrency must be a mapping, not a scalar: {lines[starts[0]]!r}") fields = {} for line in lines[starts[0] + 1:]: stripped = line.strip() if stripped and not line.startswith(" "): break # the next top-level key if not stripped or stripped.startswith("#"): continue if not line.startswith(" ") or line.startswith(" "): raise AssertionError(f"unexpected indentation under concurrency: {line!r}") key, separator, value = stripped.partition(":") if not separator: raise AssertionError(f"not a field of concurrency: {line!r}") fields[key.strip()] = value.strip() return fields def pull_request(number, run_id): # github.ref for a pull request is refs/pull//merge: the PR number, never the branch name. return (PULL_REQUEST, f"refs/pull/{number}/merge", run_id) def other_run(event_name, ref, run_id): return (event_name, ref, run_id) MAIN, TAG = ("refs/heads/main", "refs/tags/v1.2.3") SAME_GROUP = [ ("a newer commit on the same pull request", pull_request(1316, 43599251877), pull_request(1316, 43600899878)), ("a rerun of one main run", other_run(PUSH, MAIN, 7001), other_run(PUSH, MAIN, 7001)), ] DIFFERENT_GROUPS = [ ("two pull requests", pull_request(1316, 1), pull_request(1317, 1)), ("the same branch name in two forks", pull_request(1316, 2), pull_request(1400, 2)), ("two pushes to main", other_run(PUSH, MAIN, 3), other_run(PUSH, MAIN, 4)), ("two release tag runs", other_run(PUSH, TAG, 5), other_run(PUSH, TAG, 6)), ("two manual runs", other_run(DISPATCH, MAIN, 7), other_run(DISPATCH, MAIN, 8)), ("a main push and a pull request", other_run(PUSH, MAIN, 9), pull_request(1316, 9)), ("a release tag and a pull request", other_run(PUSH, TAG, 10), pull_request(1316, 10)), ] CANCELLATION = [ ("a push supersedes the previous run of its pull request", pull_request(1316, 11), True), ("a push to main is never cancelled", other_run(PUSH, MAIN, 12), False), ("a release tag run is never cancelled", other_run(PUSH, TAG, 13), False), ("a manual run is never cancelled", other_run(DISPATCH, MAIN, 14), False), ] class ConcurrencyTests(unittest.TestCase): workflow = DEFAULT_WORKFLOW @classmethod def setUpClass(cls): cls.text = cls.workflow.read_text() cls.fields = read_concurrency(cls.text) cls.group_shape = GROUP_SHAPE.fullmatch(cls.fields.get("group", "")) cls.cancel_shape = CANCEL_SHAPE.fullmatch(cls.fields.get("cancel-in-progress", "")) if not cls.group_shape or not cls.cancel_shape: raise AssertionError(f"the concurrency fields are not the documented shapes: {cls.fields}") def cancels(self, event_name): return event_name == self.cancel_shape["event"] def group(self, event_name, ref, run_id): return self.group_shape["prefix"] + "-" + (ref if event_name == self.group_shape["event"] else str(run_id)) def test_policy_is_the_two_documented_fields(self): self.assertEqual(sorted(self.fields), ["cancel-in-progress", "group"]) self.assertEqual(self.group_shape["prefix"], "workspace") self.assertEqual(self.group_shape["event"], PULL_REQUEST) self.assertEqual(self.cancel_shape["event"], PULL_REQUEST) def test_a_scalar_concurrency_value_is_not_read_as_a_mapping(self): cases = { "a block scalar": "concurrency: |\n group: workspace-x\n cancel-in-progress: true\n", "a plain scalar": "concurrency: workspace-x\njobs: {}\n", } for description, text in cases.items(): with self.subTest(description): with self.assertRaises(AssertionError): read_concurrency(text) def test_one_group_per_pull_request_and_run(self): for description, first, second in SAME_GROUP: with self.subTest(description): self.assertEqual(self.group(*first), self.group(*second), description) for description, first, second in DIFFERENT_GROUPS: with self.subTest(description): self.assertNotEqual(self.group(*first), self.group(*second), description) def test_only_a_pull_request_cancels(self): for description, context, expected in CANCELLATION: with self.subTest(description): self.assertEqual(self.cancels(context[0]), expected, description) def test_pyyaml_reads_the_same_fields(self): if yaml is None: self.skipTest("PyYAML is not installed; the limited reader above ran alone") document = yaml.load(self.text, Loader=yaml.BaseLoader) # BaseLoader keeps `on:` a string self.assertEqual(document["concurrency"], self.fields) def test_no_per_job_concurrency_is_added(self): indented = [line for line in self.text.splitlines() if line.strip().startswith("concurrency:") and not line.startswith("concurrency:")] self.assertEqual(indented, [], "the policy belongs to the workflow, not to one job") def main(): parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) parser.add_argument("--workflow", type=Path, default=DEFAULT_WORKFLOW, help="workflow to read (default: %(default)s)") arguments, remaining = parser.parse_known_args() ConcurrencyTests.workflow = arguments.workflow unittest.main(argv=[sys.argv[0], *remaining]) if __name__ == "__main__": main()