Compare commits

...
Author SHA1 Message Date
james.maesandCodex 0cd19313e7 feat: reconcile shared native GitOps consumers
Co-Authored-By: Codex <noreply@openai.com>
2026-10-21 22:44:07 -05:00
11 changed files with 211 additions and 39 deletions

No files matched your search

+1
View File
@@ -59,6 +59,7 @@ jobs:
python3 tests/test_rollout_version.py
python3 tests/test_enforce_orb_checks.py
python3 tests/test_native_next_gates.py
python3 tests/test_native_gitops_gates.py
python3 tests/test_enroll_consumers.py
python3 tests/test_reconcile_enrollment.py
python3 tests/test_discover_enrollment.py
+10 -8
View File
@@ -1,9 +1,11 @@
# GitOps validation
# 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.
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.
+4 -1
View File
@@ -426,7 +426,10 @@
"uses": "QRun-IO/qqq-orb/.github/workflows/gitops.yml@WORKER_SHA"
}
}
}
},
"additional_repositories": [
"QRun-IO/voyage-cd"
]
},
"qbit-codeql": {
"repository": null,
+4 -3
View File
@@ -340,7 +340,8 @@ class AuditTests(unittest.TestCase):
self.assertIn('missing_native_maintenance_bridge', [f['code'] for f in report['findings']])
def test_approved_no_ci_is_exact_allowlist_with_evidence_not_check_pass(self):
self.assertEqual(8, len(audit.NO_CI))
self.assertEqual(7, len(audit.NO_CI))
self.assertNotIn("QRun-IO/voyage-cd", audit.NO_CI)
for repository, policy in audit.NO_CI.items():
entry = dict(ENTRY, name=repository.split('/')[-1], nameWithOwner=repository)
files = {path: 'identity fixture' for path in policy['required_paths']}
@@ -362,13 +363,13 @@ class AuditTests(unittest.TestCase):
self.assertIn('profile_not_assigned', [f['code'] for f in report['findings']])
def test_native_specialists_require_bridges_and_report_remaining_workflows(self):
for name, kind in [('qqq-mcp-rag', 'mcp-rag'), ('qqq-business-platform', 'business-db'), ('.github', 'github-workflow-lint'), ('marketing-website-cd', 'gitops')]:
for name, kind in [('qqq-mcp-rag', 'mcp-rag'), ('qqq-business-platform', 'business-db'), ('.github', 'github-workflow-lint'), ('marketing-website-cd', 'gitops'), ('voyage-cd', 'gitops')]:
entry = dict(ENTRY, name=name, nameWithOwner='QRun-IO/' + name)
definition = audit.auxiliary.BRIDGES[kind]
missing = audit.audit(entry, Snapshot({}), VERSION, SHA, {})
self.assertIn('missing_native_maintenance_bridge', [f['code'] for f in missing['findings']])
files = {item['path']: audit.generator.yaml.safe_dump(audit.auxiliary.canonical(key, SHA), sort_keys=False)
for key, item in audit.auxiliary.BRIDGES.items() if item['repository'] == entry['nameWithOwner']}
for key, item in audit.auxiliary.BRIDGES.items() if item['repository'] == entry['nameWithOwner'] or entry['nameWithOwner'] in item.get('additional_repositories', [])}
report = audit.audit(entry, Snapshot(files), VERSION, SHA, {})
self.assertEqual([], report['findings'])
self.assertEqual('unknown', report['status'])
+112
View File
@@ -0,0 +1,112 @@
"""Native GitOps discovery must prove shared ownership without adding Circle jobs."""
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_gitops_gates as gitops
import reconcile_enrollment as remote
import enforce_orb_checks as enforcement
import finish_enrollment as finish
class GitOpsTests(unittest.TestCase):
def setUp(self):
self.pin, self.head = 'a' * 40, 'b' * 40
self.repo = 'QRun-IO/voyage-cd'
self.caller = gitops.bridge.canonical('gitops', self.pin)
self.signed, self.worker_drift, self.truncated = True, False, False
self.paths = ['.github/workflows/validate.yml', 'base/kustomization.yaml']
self.runs = [{'id': 1, 'name': 'gitops / validate', 'app': {'id': 15368},
'status': 'completed', 'conclusion': 'success'}]
self.before = {'required_status_checks': {'strict': True, 'checks': gitops.gates()},
'enforce_admins': {'enabled': True}}
def request(self, path, method='GET', payload=None):
self.assertEqual(method, 'GET')
if '/contents/' in path:
self.assertNotIn('.circleci/', path)
if '/QRun-IO/qqq-orb/' in path:
raw = (ROOT / '.github/workflows/gitops.yml').read_text() + ('# drift' if self.worker_drift else '')
else:
raw = yaml.safe_dump(self.caller, 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} 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_discovery_returns_unchanged_native_plan_without_circle_reads_or_writes(self):
for repo in sorted(gitops.REPOSITORIES):
with mock.patch.object(remote, 'api', side_effect=self.request):
plan = remote.inspect({'repository': repo, 'branch': 'main'}, '0.8')
self.assertEqual(plan['profile'], 'native-gitops')
self.assertFalse(plan['changed'])
self.assertEqual(plan['worker_pin'], self.pin)
self.assertEqual(remote.apply(plan), {'state': 'unchanged'})
self.assertEqual(finish.merge_ready(plan, {'state': 'unchanged'}), {'state': 'unchanged'})
def test_enforcement_retains_bound_native_gate(self):
plan = enforcement.inspect(self.repo, 'main', '0.8', self.request)
self.assertFalse(plan['changed'])
self.assertEqual(plan['gates'], gitops.gates())
enforcement.enforce(plan, self.request)
def test_wrong_app_and_failed_gate_reject(self):
for field, value in [('app', {'id': 18001}), ('conclusion', 'failure')]:
original = copy.deepcopy(self.runs)
self.runs[0][field] = value
with self.assertRaises(ValueError):
enforcement.inspect(self.repo, 'main', '0.8', self.request)
self.runs = original
def test_noncanonical_or_unsigned_or_changed_worker_rejects(self):
self.caller['jobs']['gitops']['uses'] = 'other/repo/workflow.yml@' + self.pin
with self.assertRaisesRegex(ValueError, 'canonical'):
gitops.validate(self.repo, self.head, 'main', self.request, yaml.safe_load)
self.caller = gitops.bridge.canonical('gitops', self.pin)
self.signed = False
with self.assertRaisesRegex(ValueError, 'not verified'):
gitops.validate(self.repo, self.head, 'main', self.request, yaml.safe_load)
self.signed, self.worker_drift = True, True
with self.assertRaisesRegex(ValueError, 'supported contract'):
gitops.validate(self.repo, self.head, 'main', self.request, yaml.safe_load)
def test_additional_orchestration_and_incomplete_inventory_reject(self):
for path in ['.circleci/config.yml', '.github/workflows/custom.yaml']:
self.paths.append(path)
with self.assertRaisesRegex(ValueError, 'additional orchestration'):
gitops.validate(self.repo, self.head, 'main', self.request, yaml.safe_load)
self.paths.pop()
self.truncated = True
with self.assertRaisesRegex(ValueError, 'complete source tree'):
gitops.validate(self.repo, self.head, 'main', self.request, yaml.safe_load)
def test_unknown_repository_and_develop_are_not_exempted(self):
for repo, branch in [('QRun-IO/unknown', 'main'), (self.repo, 'develop')]:
with self.assertRaises(ValueError):
gitops.validate(repo, self.head, branch, self.request, yaml.safe_load)
def test_native_pr_qualification(self):
with mock.patch.object(finish.remote, 'api', side_effect=self.request):
self.assertEqual(finish.qualification(self.repo, self.head, 'native-gitops'), [])
self.runs = []
self.assertEqual(finish.qualification(self.repo, self.head, 'native-gitops'), ['gitops / validate'])
if __name__ == '__main__':
unittest.main()
+3 -2
View File
@@ -46,7 +46,7 @@ PROFILES = {'qqq': 'core', 'qqq-frontend-material-dashboard': 'frontend-material
'qqq-android': 'android', 'qqq-mcp-rag-standard-policies': 'mcp-policy',
'marketing-website': 'marketing', 'qqq-mcp-rag': 'native-mcp',
'qqq-business-platform': 'native-business', '.github': 'native-workflow-lint',
'qqq-orb': 'owner-bootstrap', 'marketing-website-cd': 'native-gitops'}
'qqq-orb': 'owner-bootstrap', 'marketing-website-cd': 'native-gitops', 'voyage-cd': 'native-gitops'}
NO_CI = json.loads((ROOT / 'tools/no-ci-policy.json').read_text(encoding='utf-8'))
@@ -270,7 +270,8 @@ def audit(entry, snapshot, version, worker_sha, policy):
if profile not in ('qbit', 'repository-policy', 'all') or 'codeql_worker_sha' not in policy:
continue
bridge_sha = policy['codeql_worker_sha']
elif definition['repository'] != entry['nameWithOwner']:
elif (definition['repository'] != entry['nameWithOwner']
and entry['nameWithOwner'] not in definition.get('additional_repositories', [])):
continue
path = definition['path']
raw = snapshot.read(path)
+18 -9
View File
@@ -19,13 +19,18 @@ PROFILE_GATES = {profile: 'verify' for profile in (
PROFILE_GATES.update({'all': 'verify-and-smoke', 'cli': 'test_only',
'app-starter': 'test_only', 'android': 'test-and-build',
'mcp-policy': 'validate'})
PROFILES = set(PROFILE_GATES) | {'frontend-next'}
PROFILES = set(PROFILE_GATES) | {'frontend-next', 'native-gitops'}
_native_spec = importlib.util.spec_from_file_location('native_next_gates', ROOT / 'tools/native_next_gates.py')
native = importlib.util.module_from_spec(_native_spec)
_native_spec.loader.exec_module(native)
_gitops_spec = importlib.util.spec_from_file_location('native_gitops_gates', ROOT / 'tools/native_gitops_gates.py')
gitops = importlib.util.module_from_spec(_gitops_spec)
_gitops_spec.loader.exec_module(gitops)
def gates(profile):
if profile == 'native-gitops':
return gitops.gates()
if profile == 'frontend-next':
return native.gates(pull_request=True)
return [{'context': name, 'app_id': 18001}
@@ -110,14 +115,18 @@ def inspect(repo, branch, version, request=api):
raise ValueError('Archived repository')
prefix = root + '/branches/' + branch
head = request(prefix)['commit']['sha']
source = []
for path in ('.circleci/config.yml', '.qqq-ci.yml'):
item = request(root + '/contents/' + quote(path, safe='/') + '?ref=' + head)
if item.get('encoding') != 'base64' or item.get('type') != 'file':
raise ValueError('Canonical declarations must be regular files')
source.append(base64.b64decode(item['content'], validate=False).decode('utf-8'))
standard.validate(*source, version)
profile = standard.load_yaml(source[1])['profile']
if repo in gitops.REPOSITORIES:
gitops.validate(repo, head, branch, request, standard.load_yaml)
profile = 'native-gitops'
else:
source = []
for path in ('.circleci/config.yml', '.qqq-ci.yml'):
item = request(root + '/contents/' + quote(path, safe='/') + '?ref=' + head)
if item.get('encoding') != 'base64' or item.get('type') != 'file':
raise ValueError('Canonical declarations must be regular files')
source.append(base64.b64decode(item['content'], validate=False).decode('utf-8'))
standard.validate(*source, version)
profile = standard.load_yaml(source[1])['profile']
if profile not in PROFILES:
raise ValueError('Profile has no supported shared branch gates')
desired_gates = gates(profile)
+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'] == 'native-gitops':
enforcement.gitops.validate(repo, head, plan['branch'], remote.api, enforcement.standard.load_yaml)
if plan['profile'] == 'frontend-next':
enforcement.native.validate(repo, head, plan['branch'], remote.api, enforcement.standard.load_yaml)
pending = qualification(repo, head, plan['profile'])
+51
View File
@@ -0,0 +1,51 @@
"""Recognize approved GitOps repositories through their shared immutable worker."""
import base64
import importlib.util
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
spec = importlib.util.spec_from_file_location('gitops_bridge', ROOT / 'src/scripts/generate_auxiliary_workflow.py')
bridge = importlib.util.module_from_spec(spec)
spec.loader.exec_module(bridge)
DEFINITION = bridge.BRIDGES['gitops']
REPOSITORIES = {DEFINITION['repository'], *DEFINITION.get('additional_repositories', [])}
def gates():
return [{'context': 'gitops / validate', 'app_id': 15368}]
def validate(repo, head, branch, request, load_yaml):
if repo not in REPOSITORIES or branch != 'main':
raise ValueError('GitOps recognition requires an approved repository on main only')
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('GitOps workflow must be a regular file')
return base64.b64decode(item['content']).decode('utf-8').replace('\r\n', '\n')
path = DEFINITION['path']
caller = load_yaml(content(repo, path, head))
try:
pin = caller['jobs']['gitops']['uses'].rsplit('@', 1)[1]
expected = bridge.canonical('gitops', pin)
except (KeyError, TypeError, IndexError, ValueError, AttributeError):
raise ValueError('GitOps caller has no immutable shared worker pin') from None
if caller != expected:
raise ValueError('GitOps caller differs from the canonical shared bridge')
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('GitOps recognition requires the complete source tree')
for entry in tree['tree']:
name = entry['path']
if name == '.circleci/config.yml' or (name.startswith('.github/workflows/')
and name.endswith(('.yml', '.yaml')) and name != path):
raise ValueError('GitOps repository has additional orchestration: ' + name)
commit = request('repos/QRun-IO/qqq-orb/commits/' + pin)
if not commit['commit']['verification']['verified']:
raise ValueError('GitOps worker commit is not verified')
worker = '.github/workflows/gitops.yml'
if content('QRun-IO/qqq-orb', worker, pin) != (ROOT / worker).read_text(encoding='utf-8'):
raise ValueError('Pinned GitOps worker differs from the supported contract')
return pin
-16
View File
@@ -15,22 +15,6 @@
],
"rationale": "Template source; core generated-consumer acceptance owns validation."
},
"QRun-IO/voyage-cd": {
"baseline_sha": "f8734e2d30b59af4909bd0a4c39fa6c9d6981d61",
"required_paths": [
"README.md"
],
"forbidden_prefixes": [
".circleci/",
".github/workflows/"
],
"forbidden_paths": [
".qqq-ci.yml",
"Jenkinsfile",
".gitlab-ci.yml"
],
"rationale": "GitOps deployment declarations; audited repository has no CI."
},
"QRun-IO/qqq-templates-hub": {
"baseline_sha": "bd591168c7200ce40a3535f2052b8327056e82e0",
"required_paths": [
+6
View File
@@ -11,6 +11,8 @@ import subprocess
import tempfile
import enroll_consumers
import native_gitops_gates as gitops
import yaml
PATHS = ('.circleci/config.yml', '.qqq-ci.yml')
@@ -107,6 +109,10 @@ def inspect(target, version):
if info['archived']:
raise ValueError('Archived repository')
head = api(f'repos/{repo}/branches/{branch}')['commit']['sha']
if repo in gitops.REPOSITORIES:
pin = gitops.validate(repo, head, branch, api, yaml.safe_load)
return {**target, 'head': head, 'profile': 'native-gitops', 'version': version,
'changed': False, 'worker_pin': pin}
originals = {path: content(repo, path, head) for path in PATHS}
if originals[PATHS[0]] is None:
raise ValueError('No recognized CircleCI entrypoint')