diff --git a/.github/check_workflow_triggers.py b/.github/check_workflow_triggers.py new file mode 100755 index 00000000..eea380b2 --- /dev/null +++ b/.github/check_workflow_triggers.py @@ -0,0 +1,127 @@ +#!/usr/bin/env python3 +"""Fail if a workflow's push or pull_request trigger can never match. + +A branch filter naming a branch that does not exist leaves the workflow +configured but never scheduled, which looks identical to a workflow that +runs and passes: no red check appears, because no check appears at all. + +Only filters whose positive entries are all literal names are judged. A +filter holding a glob is left alone, since whether it can match depends on +branches that may not exist yet. A filter of only !exclusions never matches. + + usage: check_workflow_triggers.py [workflow-dir] +""" +import glob +import os +import subprocess +import sys + +import yaml + +GLOB_CHARS = set('*?[]+@') + + +def existing_branches(): + """Branch names on the remote, falling back to local refs.""" + for cmd in (['git', 'ls-remote', '--heads', 'origin'], + ['git', 'for-each-ref', '--format=%(refname)', 'refs/remotes/origin'], + ['git', 'for-each-ref', '--format=%(refname)', 'refs/heads']): + out = subprocess.run(cmd, capture_output=True, text=True) + if out.returncode == 0 and out.stdout.strip(): + names = set() + for line in out.stdout.split('\n'): + line = line.strip() + for prefix in ('refs/heads/', 'refs/remotes/origin/'): + if prefix in line: + ref = line.split(prefix, 1)[1] + if ref and ref != 'HEAD': + names.add(ref) + if names: + return names + return set() + + +def default_branch(): + env = os.environ.get('DEFAULT_BRANCH') + if env: + return env.strip() + out = subprocess.run(['git', 'symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], + capture_output=True, text=True) + if out.returncode == 0 and out.stdout.strip(): + return out.stdout.strip().split('/')[-1] + return None + + +def triggers(doc): + """The `on:` mapping. PyYAML reads an unquoted `on` key as True.""" + for key in (True, 'on', 'On', 'ON'): + if isinstance(doc, dict) and key in doc: + return doc[key] + return None + + +def main(argv): + where = argv[1] if len(argv) > 1 else '.github/workflows' + branches = existing_branches() + default = default_branch() + if not branches: + print('could not determine the repository branches; nothing checked') + return 1 if os.environ.get('CI') else 0 + print('branches on the remote: %d, default: %s' + % (len(branches), default or 'unknown')) + + problems = [] + for path in sorted(glob.glob(os.path.join(where, '*.yml')) + + glob.glob(os.path.join(where, '*.yaml'))): + try: + with open(path, encoding='utf-8') as f: + doc = yaml.safe_load(f) + except yaml.YAMLError as exc: + problems.append('%s: cannot parse: %s' % (path, exc)) + continue + on = triggers(doc) + if not isinstance(on, dict): + continue + for event in ('push', 'pull_request', 'pull_request_target'): + spec = on.get(event) + if not isinstance(spec, dict): + continue + names = spec.get('branches') + if not names: + continue + if isinstance(names, str): + names = [names] + if not isinstance(names, list) or not all(isinstance(n, str) for n in names): + problems.append('%s: %s.branches must be a list of quoted strings, ' + 'got %r' % (path, event, names)) + continue + positive = [n for n in names if not n.startswith('!')] + if not positive: + problems.append('%s: %s.branches has only !exclusions, which match ' + 'no branch' % (path, event)) + continue + if any(GLOB_CHARS & set(n) for n in positive): + continue + names = positive + live = [n for n in names if n in branches] + if not live: + problems.append( + '%s: %s.branches names only %s, and no such branch exists.\n' + ' This workflow can never be scheduled.%s' + % (path, event, ', '.join(repr(n) for n in names), + ('\n The default branch is %r.' % default) if default else '')) + elif default and default not in names: + print('note: %s: %s.branches does not include the default ' + 'branch %r' % (path, event, default)) + + if problems: + print('\nWorkflow trigger check failed:\n') + for p in problems: + print(' ' + p) + return 1 + print('every push and pull_request trigger can match an existing branch') + return 0 + + +if __name__ == '__main__': + sys.exit(main(sys.argv)) diff --git a/.github/test_check_workflow_triggers.py b/.github/test_check_workflow_triggers.py new file mode 100644 index 00000000..5992cbbd --- /dev/null +++ b/.github/test_check_workflow_triggers.py @@ -0,0 +1,57 @@ +#!/usr/bin/env python3 +"""Tests for check_workflow_triggers.py; run: python3 .github/test_check_workflow_triggers.py""" +import contextlib +import importlib.util +import io +import os +import tempfile +import unittest +from unittest import mock + +_HERE = os.path.dirname(os.path.abspath(__file__)) +_SPEC = importlib.util.spec_from_file_location( + 'check_workflow_triggers', os.path.join(_HERE, 'check_workflow_triggers.py')) +cwt = importlib.util.module_from_spec(_SPEC) +_SPEC.loader.exec_module(cwt) + + +class CheckWorkflowTriggers(unittest.TestCase): + + def run_check(self, branches_yaml, existing=('master',), env=None): + with tempfile.TemporaryDirectory() as where: + with open(os.path.join(where, 'w.yml'), 'w', encoding='utf-8') as f: + f.write('on:\n push:\n branches: %s\n' % branches_yaml) + with mock.patch.object(cwt, 'existing_branches', lambda: set(existing)), \ + mock.patch.object(cwt, 'default_branch', lambda: 'master'), \ + mock.patch.dict(os.environ, env or {}, clear=False), \ + contextlib.redirect_stdout(io.StringIO()): + return cwt.main(['check', where]) + + def test_existing_literal_branch_passes(self): + self.assertEqual(self.run_check('[ master ]'), 0) + + def test_missing_literal_branch_fails(self): + self.assertEqual(self.run_check('[ main ]'), 1) + + def test_glob_is_not_judged(self): + self.assertEqual(self.run_check("[ 'release-*' ]"), 0) + + def test_bare_string_is_one_branch(self): + self.assertEqual(self.run_check('master'), 0) + + def test_unquoted_non_string_entry_fails(self): + self.assertEqual(self.run_check('[ on ]'), 1) + self.assertEqual(self.run_check('[ 3.0 ]'), 1) + + def test_exclusion_does_not_hide_missing_branch(self): + self.assertEqual(self.run_check("[ main, '!wip' ]"), 1) + + def test_only_exclusions_fails(self): + self.assertEqual(self.run_check("[ '!wip' ]"), 1) + + def test_no_branches_found_fails_in_ci(self): + self.assertEqual(self.run_check('[ master ]', existing=(), env={'CI': 'true'}), 1) + + +if __name__ == '__main__': + unittest.main() diff --git a/.github/workflows/cmake-multi-platform.yml b/.github/workflows/cmake-multi-platform.yml index 9723123c..52358146 100644 --- a/.github/workflows/cmake-multi-platform.yml +++ b/.github/workflows/cmake-multi-platform.yml @@ -269,3 +269,22 @@ jobs: # A test that cannot find a DLL can raise a modal dialog and block the # runner rather than exit, so every test carries a timeout. run: ctest --build-config Release --output-on-failure --no-tests=error --timeout 120 + + workflow-triggers: + # A branch filter naming a branch that does not exist leaves the + # workflow configured but never scheduled, which is indistinguishable + # from one that runs and passes: no red check appears because no check + # appears at all. build.yml sat dead behind `branches: [ main ]` on a + # repository whose branch is master, and nothing detected it. + name: workflow triggers can match a branch + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Install dependencies + run: python3 -c "import yaml" 2>/dev/null || (sudo apt-get update && sudo apt-get install -y python3-yaml) + - name: Test the checker + run: python3 .github/test_check_workflow_triggers.py + - name: Check the branch filters + env: + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + run: python3 .github/check_workflow_triggers.py