Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 127 additions & 0 deletions .github/check_workflow_triggers.py
Original file line number Diff line number Diff line change
@@ -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']):
Comment thread
hjmjohnson marked this conversation as resolved.
Resolved
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))
57 changes: 57 additions & 0 deletions .github/test_check_workflow_triggers.py
Original file line number Diff line number Diff line change
@@ -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()
19 changes: 19 additions & 0 deletions .github/workflows/cmake-multi-platform.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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