Compare commits

...
Author SHA1 Message Date
james.maesandCodex 45db5251d2 fix: keep qctl required gates appropriate for pull requests
Co-Authored-By: Codex <noreply@openai.com>
2026-10-22 00:33:04 -05:00
james.maesandCodex dd37011b7d feat: recognize and enforce shared native consumers
Co-Authored-By: Codex <noreply@openai.com>
2026-10-22 00:31:36 -05:00
8 changed files with 324 additions and 15 deletions

No files matched your search

+1
View File
@@ -60,6 +60,7 @@ jobs:
python3 tests/test_enforce_orb_checks.py
python3 tests/test_native_next_gates.py
python3 tests/test_native_gitops_gates.py
python3 tests/test_native_specialist_gates.py
python3 tests/test_enroll_consumers.py
python3 tests/test_reconcile_enrollment.py
python3 tests/test_discover_enrollment.py
+22 -10
View File
@@ -1,14 +1,14 @@
# GitOps validation
The orb owns `.github/workflows/gitops.yml`. The consumer keeps only the immutable caller generated by `generate_auxiliary_workflow.py gitops --ref <orb-commit>` at `.github/workflows/validate.yml`.
One native job downloads Kustomize 5.7.1 with its pinned official SHA-256 and renders every Kustomization, including bases, overlays and proxy declarations. Missing configurations or a failed render fail the job. Rendered resources are discarded rather than logged or uploaded because they may contain Secrets. This checks rendering, not Kubernetes schema compatibility or cluster health. No cluster access or publication credentials are required.
The caller runs on main pushes and pull requests without path filters, so a required check always reports. Superseded PR runs are canceled. Feature pushes do not create duplicate jobs. Remove the old Circle pipeline only after the native job passes on the consumer, then disable obsolete Circle build requests and require the observed native check with no human review.
For marketing-website-cd, the prior Circle job only printed Hello World. Its former production role moved to KofTwentyTwo/cluster-gitops; validation does not re-enable that retired deployment path.
# GitOps validation
The shared registry includes marketing-website-cd and voyage-cd. Daily enrollment recognizes their canonical main-branch caller without creating Circle configuration. Recognition requires a signed immutable worker pin matching the supported worker, a complete source tree, and no additional Circle or GitHub workflows. Enforcement requires the GitHub Actions app-bound gitops / validate gate and preserves existing branch rules. Unavailable private-repository protections remain an explicit enforcement failure; recognition alone is not enforcement.
The orb owns `.github/workflows/gitops.yml`. The consumer keeps only the immutable caller generated by `generate_auxiliary_workflow.py gitops --ref <orb-commit>` at `.github/workflows/validate.yml`.
One native job downloads Kustomize 5.7.1 with its pinned official SHA-256 and renders every Kustomization, including bases, overlays and proxy declarations. Missing configurations or a failed render fail the job. Rendered resources are discarded rather than logged or uploaded because they may contain Secrets. This checks rendering, not Kubernetes schema compatibility or cluster health. No cluster access or publication credentials are required.
The caller runs on main pushes and pull requests without path filters, so a required check always reports. Superseded PR runs are canceled. Feature pushes do not create duplicate jobs. Remove the old Circle pipeline only after the native job passes on the consumer, then disable obsolete Circle build requests and require the observed native check with no human review.
For marketing-website-cd, the prior Circle job only printed Hello World. Its former production role moved to KofTwentyTwo/cluster-gitops; validation does not re-enable that retired deployment path.
The shared registry includes marketing-website-cd and voyage-cd. Daily enrollment recognizes their canonical main-branch caller without creating Circle configuration. Recognition requires a signed immutable worker pin matching the supported worker, a complete source tree, and no additional Circle or GitHub workflows. Enforcement requires the GitHub Actions app-bound gitops / validate gate and preserves existing branch rules. Unavailable private-repository protections remain an explicit enforcement failure; recognition alone is not enforcement.
### Documentation repositories with shell automation
@@ -39,3 +39,15 @@ hooks, then performs Maven verify on the generated application with all its test
The renderer and Maven dependencies are cached; test reports and the generated JAR
are retained. This is acceptance of a generated consumer, not Maven publication.
Only the standard profile, orb version, and default branch are consumer settings.
The coordinator also recognizes qctl on main/develop and the approved .github,
business-platform, MCP-RAG and IntelliJ callers on main. It verifies each complete
workflow inventory, canonical caller, signed immutable orb pin and matching shared
worker source before recognizing the repository. Native verification gates bind to
the GitHub Actions app; release-only jobs are not merge requirements. No CircleCI
caller is added to these native consumers. qctl requires its shared tests; the native binary job is push-only, and
full platform release builds retain their existing shared-worker policy.
Existing classic branch protections without a required-status-check section gain
an additive shared ruleset. Signing, reviews, history and access restrictions remain
unchanged, and a subsequent reconciliation verifies the effective ruleset.
+15 -3
View File
@@ -203,8 +203,21 @@ class EnforcementTests(unittest.TestCase):
enforcement.verified_rulesets('QRun-IO/example', effective, lambda path: record)
def test_empty_push_allowlist_gains_ruleset_without_changing_access(self):
classic = {'restrictions': {'users': [], 'teams': [], 'apps': []},
'enforce_admins': {'enabled': False}, 'required_signatures': {'enabled': True}}
self.assert_ruleset_preserves_classic({
'restrictions': {'users': [], 'teams': [], 'apps': []},
'enforce_admins': {'enabled': False}, 'required_signatures': {'enabled': True}})
def test_existing_protection_without_status_section_gains_ruleset(self):
for admin in (False, True):
with self.subTest(enforce_admins=admin):
self.assert_ruleset_preserves_classic({
'enforce_admins': {'enabled': admin},
'required_signatures': {'enabled': True},
'required_linear_history': {'enabled': True},
'required_pull_request_reviews': {'required_approving_review_count': 2},
'required_conversation_resolution': {'enabled': True}})
def assert_ruleset_preserves_classic(self, classic):
state = {'ruleset': None, 'writes': []}
def request(path, method='GET', payload=None):
@@ -241,7 +254,6 @@ class EnforcementTests(unittest.TestCase):
self.assertEqual(1, len(state['writes']))
self.assertEqual([], state['writes'][0]['bypass_actors'])
self.assertEqual({'include': ['refs/heads/main'], 'exclude': []}, state['writes'][0]['conditions']['ref_name'])
self.assertFalse(plan['before']['enforce_admins']['enabled'])
self.assertEqual(classic, plan['before'])
repeat = enforcement.inspect('QRun-IO/example', 'main', '0.8', request)
self.assertFalse(repeat['changed'])
+149
View File
@@ -0,0 +1,149 @@
"""Native recognition proves central ownership and app-bound verification gates."""
import base64
import copy
from pathlib import Path
import sys
import unittest
from unittest import mock
import yaml
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / 'tools'))
import native_specialist_gates as native
import reconcile_enrollment as remote
import enforce_orb_checks as enforcement
import finish_enrollment as finish
class NativeTests(unittest.TestCase):
def fixture(self, repo):
self.repo, self.pin, self.head = repo, 'a' * 40, 'b' * 40
self.profile, self.branches, kinds, _ = native.DEFINITIONS[repo]
self.callers = dict(native.caller(kind, self.pin) for kind in kinds)
self.paths = list(self.callers)
self.signed, self.drift, self.truncated = True, False, False
self.mode = '100644'
self.runs = [{'id': i, 'name': gate['context'], 'app': {'id': gate['app_id']},
'status': 'completed', 'conclusion': 'success'}
for i, gate in enumerate(native.gates(self.profile))]
self.before = {'required_status_checks': {'strict': True, 'checks': native.gates(self.profile)},
'enforce_admins': {'enabled': True}}
def request(self, path, method='GET', payload=None):
self.assertEqual('GET', method)
if '/contents/' in path:
self.assertNotIn('.circleci/', path)
file = path.split('/contents/')[1].split('?')[0]
if path.startswith('repos/QRun-IO/qqq-orb/'):
raw = (ROOT / file).read_text() + ('# changed' if self.drift else '')
else:
raw = yaml.safe_dump(self.callers[file], sort_keys=False)
return {'type': 'file', 'encoding': 'base64', 'content': base64.b64encode(raw.encode()).decode()}
if '/git/trees/' in path:
return {'truncated': self.truncated, 'tree': [{'path': p, 'type': 'blob', 'mode': self.mode} for p in self.paths]}
if path.endswith('/commits/' + self.pin):
return {'commit': {'verification': {'verified': self.signed}}}
if '/check-runs?' in path:
return {'check_runs': copy.deepcopy(self.runs)}
if '/status?' in path:
return {'statuses': []}
if path.endswith('/protection'):
return copy.deepcopy(self.before)
if '/rules/branches/' in path:
return []
if '/branches/' in path:
return {'commit': {'sha': self.head}}
return {'archived': False, 'default_branch': 'main'}
def test_all_approved_callers_discover_enforce_and_qualify_without_mutation(self):
for repo in native.DEFINITIONS:
self.fixture(repo)
for branch in self.branches:
with self.subTest(repo=repo, branch=branch), mock.patch.object(remote, 'api', side_effect=self.request):
plan = remote.inspect({'repository': repo, 'branch': branch}, '0.8')
self.assertEqual(self.profile, plan['profile'])
self.assertFalse(plan['changed'])
self.assertEqual(set(self.callers), set(plan['worker_pins']))
self.assertEqual({'state': 'unchanged'}, remote.apply(plan))
self.assertEqual({'state': 'unchanged'}, finish.merge_ready(plan, {'state': 'unchanged'}))
self.assertEqual([], finish.qualification(repo, self.head, self.profile))
protected = enforcement.inspect(repo, branch, '0.8', self.request)
self.assertFalse(protected['changed'])
enforcement.enforce(protected, self.request)
def test_failed_missing_wrong_app_and_newer_failed_gate_reject(self):
for repo in native.DEFINITIONS:
self.fixture(repo)
good = copy.deepcopy(self.runs)
for bad in [[], good[1:], [dict(x, app={'id': 18001}) for x in good],
good + [dict(good[0], id=99, conclusion='failure')]]:
self.runs = bad
with self.subTest(repo=repo), self.assertRaises(ValueError):
enforcement.inspect(repo, 'main', '0.8', self.request)
def test_custom_caller_unsigned_or_changed_worker_rejects(self):
for repo in native.DEFINITIONS:
for defect in ('caller', 'unsigned', 'worker', 'mutable'):
self.fixture(repo)
if defect == 'caller':
next(iter(self.callers.values()))['extra'] = True
elif defect == 'unsigned':
self.signed = False
elif defect == 'worker':
self.drift = True
else:
jobs = next(iter(self.callers.values()))['jobs']
job = next(iter(jobs.values()))
job['uses'] = job['uses'].replace(self.pin, 'main')
with self.subTest(repo=repo, defect=defect), self.assertRaises(ValueError):
native.validate(repo, self.head, 'main', self.request)
def test_complete_workflow_inventory_required(self):
self.fixture('QRun-IO/qqq-business-platform')
for path in ('.circleci/config.yml', '.github/workflows/custom.yml', '.github/workflows/extra.yaml'):
self.paths.append(path)
with self.assertRaisesRegex(ValueError, 'additional orchestration'):
native.validate(self.repo, self.head, 'main', self.request)
self.paths.pop()
self.truncated = True
with self.assertRaisesRegex(ValueError, 'complete source tree'):
native.validate(self.repo, self.head, 'main', self.request)
def test_symlinked_or_missing_caller_rejects(self):
self.fixture('QRun-IO/qctl')
self.mode = '120000'
with self.assertRaisesRegex(ValueError, 'regular source file'):
native.validate(self.repo, self.head, 'main', self.request)
self.paths = []
with self.assertRaisesRegex(ValueError, 'regular source file'):
native.validate(self.repo, self.head, 'main', self.request)
def test_unknown_repo_and_unapproved_branch_reject(self):
self.fixture('QRun-IO/qqq-mcp-rag')
for repo, branch in [('QRun-IO/unknown', 'main'), (self.repo, 'develop'), ('QRun-IO/qctl', 'release/old')]:
with self.assertRaises(ValueError):
native.validate(repo, self.head, branch, self.request)
def test_qctl_pr_gate_excludes_push_only_native_binary_job(self):
worker = native.load_workflow((ROOT / '.github/workflows/qctl-native.yml').read_text())
self.assertNotIn('if', worker['jobs']['test'])
self.assertEqual("github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.full_native)",
worker['jobs']['build-native']['if'])
self.assertEqual([{'context': 'native / test', 'app_id': 15368}], native.gates('qctl'))
def test_github_yaml_events_and_duplicate_keys(self):
self.assertEqual({'on': {'push': None}, 'enabled': True},
native.load_workflow('on:\n push:\nenabled: true\n'))
for raw in ('on: {}\non: {}\n', 'jobs: {build: {}, build: {}}\n', '1: value\n'):
with self.subTest(raw=raw), self.assertRaises(ValueError):
native.load_workflow(raw)
def test_native_enforcement_preserves_other_required_checks(self):
self.fixture('QRun-IO/qctl')
self.before['required_status_checks']['checks'].append({'context': 'security', 'app_id': 15368})
plan = enforcement.inspect(self.repo, 'main', '0.8', self.request)
self.assertIn({'context': 'security', 'app_id': 15368}, plan['required_status_checks']['checks'])
if __name__ == '__main__':
unittest.main()
+15 -2
View File
@@ -27,8 +27,15 @@ _gitops_spec = importlib.util.spec_from_file_location('native_gitops_gates', ROO
gitops = importlib.util.module_from_spec(_gitops_spec)
_gitops_spec.loader.exec_module(gitops)
_specialist_spec = importlib.util.spec_from_file_location('native_specialist_gates', ROOT / 'tools/native_specialist_gates.py')
specialists = importlib.util.module_from_spec(_specialist_spec)
_specialist_spec.loader.exec_module(specialists)
PROFILES |= specialists.PROFILES
def gates(profile):
if profile in specialists.PROFILES:
return specialists.gates(profile)
if profile == 'native-gitops':
return gitops.gates()
if profile == 'frontend-next':
@@ -115,7 +122,9 @@ def inspect(repo, branch, version, request=api):
raise ValueError('Archived repository')
prefix = root + '/branches/' + branch
head = request(prefix)['commit']['sha']
if repo in gitops.REPOSITORIES:
if repo in specialists.DEFINITIONS:
profile, _ = specialists.validate(repo, head, branch, request)
elif repo in gitops.REPOSITORIES:
gitops.validate(repo, head, branch, request, standard.load_yaml)
profile = 'native-gitops'
else:
@@ -138,9 +147,13 @@ def inspect(repo, branch, version, request=api):
rulesets, ruleset_strict = verified_rulesets(repo, rules, request, desired_gates) if rules else ([], False)
before = request(prefix + '/protection')
restrictions = (before or {}).get('restrictions')
use_ruleset = (not rulesets and restrictions is not None
missing_status_section = before is not None and before.get('required_status_checks') is None
empty_push_allowlist = (restrictions is not None
and not any(restrictions.get(kind) for kind in ('users', 'teams', 'apps'))
and not (before or {}).get('enforce_admins', {}).get('enabled'))
# GitHub cannot PATCH a missing status-check subresource. An additive ruleset
# preserves the existing signing, review, history and access policies.
use_ruleset = not rulesets and (missing_status_section or empty_push_allowlist)
runs = []
page = 1
while True:
+2
View File
@@ -50,6 +50,8 @@ def merge_ready(plan, result):
if pr['state'] != 'MERGED':
if pr['baseRefOid'] != plan['head'] or remote.api(f'repos/{repo}/branches/{plan["branch"]}')['commit']['sha'] != plan['head']:
return {'state': 'stale-base', 'url': result['url']}
if plan['profile'] in enforcement.specialists.PROFILES:
enforcement.specialists.validate(repo, head, plan['branch'], remote.api)
if plan['profile'] == 'native-gitops':
enforcement.gitops.validate(repo, head, plan['branch'], remote.api, enforcement.standard.load_yaml)
if plan['profile'] == 'frontend-next':
+115
View File
@@ -0,0 +1,115 @@
"""Recognize reviewed native consumers and their shared immutable orb workers."""
import base64
import importlib.util
import re
from pathlib import Path
import yaml
ROOT = Path(__file__).resolve().parents[1]
def module(name):
spec = importlib.util.spec_from_file_location(name, ROOT / 'src/scripts' / (name + '.py'))
result = importlib.util.module_from_spec(spec)
spec.loader.exec_module(result)
return result
auxiliary = module('generate_auxiliary_workflow')
qctl = module('generate_qctl_workflow')
standard = module('validate_standard')
class WorkflowLoader(standard.UniqueLoader):
# GitHub uses YAML 1.2: unquoted "on" is an event key, not a boolean.
yaml_implicit_resolvers = {
key: [(tag, pattern) for tag, pattern in values if tag != 'tag:yaml.org,2002:bool']
for key, values in standard.UniqueLoader.yaml_implicit_resolvers.items()
}
WorkflowLoader.add_implicit_resolver('tag:yaml.org,2002:bool', re.compile(r'^(true|false)$', re.I), list('tTfF'))
def load_workflow(raw):
try:
return yaml.load(raw, Loader=WorkflowLoader)
except yaml.YAMLError as error:
raise ValueError('Invalid native workflow YAML') from error
# Only observed, mandatory verification gates; release-only jobs are not PR gates.
DEFINITIONS = {
'QRun-IO/qctl': ('qctl', ('main', 'develop'), ('qctl',),
('native / test',)),
'QRun-IO/.github': ('native-workflow-lint', ('main',), ('github-workflow-lint',),
('actionlint / actionlint',)),
'QRun-IO/qqq-business-platform': ('native-business', ('main',), ('business-db', 'business-e2e'),
('validate / empty-database-migration', 'validate / Deployment gate / E2E passed')),
'QRun-IO/qqq-mcp-rag': ('native-mcp', ('main',), ('mcp-rag',),
('validate / Build and Test',)),
'QRun-IO/qqq-app-developer-intellij-plugin': ('intellij-plugin', ('main',), ('intellij-plugin',),
('plugin / build',)),
}
PROFILES = {definition[0] for definition in DEFINITIONS.values()}
def gates(profile):
names = next(definition[3] for definition in DEFINITIONS.values() if definition[0] == profile)
return [{'context': name, 'app_id': 15368} for name in names]
def caller(kind, pin):
if kind == 'qctl':
return '.github/workflows/build.yml', load_workflow(qctl.generate(pin))
return auxiliary.BRIDGES[kind]['path'], auxiliary.canonical(kind, pin)
def validate(repo, head, branch, request):
if repo not in DEFINITIONS or branch not in DEFINITIONS[repo][1]:
raise ValueError('Native recognition requires an approved repository and branch')
profile, _, kinds, _ = DEFINITIONS[repo]
def content(owner, path, ref):
item = request(f'repos/{owner}/contents/{path}?ref={ref}')
if item.get('type') != 'file' or item.get('encoding') != 'base64':
raise ValueError('Native workflow must be a regular file')
return base64.b64decode(item['content']).decode('utf-8').replace('\r\n', '\n')
paths, pins, verified = set(), {}, set()
for kind in kinds:
path, _ = caller(kind, '0' * 40)
actual = load_workflow(content(repo, path, head))
try:
pin = next(iter(actual['jobs'].values()))['uses'].rsplit('@', 1)[1]
_, expected = caller(kind, pin)
except (KeyError, TypeError, IndexError, ValueError, AttributeError, StopIteration):
raise ValueError('Native caller has no immutable orb pin') from None
if actual != expected:
raise ValueError('Native caller differs from the canonical shared bridge')
if pin not in verified:
commit = request('repos/QRun-IO/qqq-orb/commits/' + pin)
if not commit['commit']['verification']['verified']:
raise ValueError('Native worker commit is not verified')
verified.add(pin)
for job in expected['jobs'].values():
worker = job['uses'].split('@')[0].removeprefix('QRun-IO/qqq-orb/')
if content('QRun-IO/qqq-orb', worker, pin) != (ROOT / worker).read_text(encoding='utf-8'):
raise ValueError('Pinned native worker differs from the supported contract')
paths.add(path)
pins[path] = pin
tree = request(f'repos/{repo}/git/trees/{head}?recursive=1')
if tree.get('truncated') is not False or not isinstance(tree.get('tree'), list):
raise ValueError('Native recognition requires the complete source tree')
entries = {entry['path']: entry for entry in tree['tree']}
for path in paths:
entry = entries.get(path, {})
if entry.get('type') != 'blob' or entry.get('mode') not in ('100644', '100755'):
raise ValueError('Native caller is missing or is not a regular source file')
for entry in tree['tree']:
path = entry['path']
if path == '.circleci/config.yml' or (path.startswith('.github/workflows/')
and path.endswith(('.yml', '.yaml')) and path not in paths):
raise ValueError('Native repository has additional orchestration: ' + path)
return profile, pins
+5
View File
@@ -12,6 +12,7 @@ import tempfile
import enroll_consumers
import native_gitops_gates as gitops
import native_specialist_gates as specialists
import yaml
PATHS = ('.circleci/config.yml', '.qqq-ci.yml')
@@ -109,6 +110,10 @@ def inspect(target, version):
if info['archived']:
raise ValueError('Archived repository')
head = api(f'repos/{repo}/branches/{branch}')['commit']['sha']
if repo in specialists.DEFINITIONS:
profile, pins = specialists.validate(repo, head, branch, api)
return {**target, 'head': head, 'profile': profile, 'version': version,
'changed': False, 'worker_pins': pins}
if repo in gitops.REPOSITORIES:
pin = gitops.validate(repo, head, branch, api, yaml.safe_load)
return {**target, 'head': head, 'profile': 'native-gitops', 'version': version,