Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
6dd473be25
|
||
|
|
1c8a7c57e5 |
No files matched your search
@@ -57,6 +57,7 @@ jobs:
|
||||
python3 tests/test_ci_maintenance.py
|
||||
python3 tests/test_rollout_version.py
|
||||
python3 tests/test_enforce_orb_checks.py
|
||||
python3 tests/test_enroll_consumers.py
|
||||
python3 tests/test_static_analysis_exit.py
|
||||
python3 tests/test_validate_standard.py
|
||||
python3 tests/test_voyage_profile.py
|
||||
|
||||
@@ -62,6 +62,7 @@ test-pipelines: pack
|
||||
python3 tests/test_ci_maintenance.py
|
||||
python3 tests/test_rollout_version.py
|
||||
python3 tests/test_enforce_orb_checks.py
|
||||
python3 tests/test_enroll_consumers.py
|
||||
python3 tests/test_static_analysis_exit.py
|
||||
python3 tests/test_validate_standard.py
|
||||
python3 tests/test_voyage_profile.py
|
||||
|
||||
@@ -136,3 +136,8 @@ For a qualified batch of canonical orb branches, use the shared
|
||||
CircleCI setup/verify gates while preserving other protections. Source enrollment,
|
||||
scanner transitions and scheduled reconciliation remain separate requirements.
|
||||
Scheduling and authenticated onboarding still need to be configured centrally.
|
||||
|
||||
## Batch enrollment
|
||||
|
||||
Use [the shared enrollment command](consumer-enrollment.md) to convert recognized
|
||||
legacy QBits and update existing canonical consumers in one validated batch.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Batch consumer enrollment
|
||||
|
||||
Use one target file for canonical consumers of every supported Circle profile and
|
||||
legacy QBits whose jobs and publication filters the shared converter recognizes:
|
||||
|
||||
```json
|
||||
[
|
||||
{"checkout": "/work/qbit-example", "default_branch": "main"},
|
||||
{"checkout": "/work/qqq", "default_branch": "develop"}
|
||||
]
|
||||
```
|
||||
|
||||
The branch values must come from repository inventory. Run on clean isolated
|
||||
checkouts of the branches being migrated.
|
||||
|
||||
```sh
|
||||
python tools/enroll_consumers.py targets.json --orb-version 0.8
|
||||
python tools/enroll_consumers.py targets.json --orb-version 0.8 --write
|
||||
```
|
||||
|
||||
The command validates the entire batch before writing. Existing manifests keep
|
||||
all publication and profile options; only the managed orb version changes.
|
||||
Recognized legacy QBits receive the canonical caller and inferred publication
|
||||
policy. An unknown job, filter, profile option, duplicate target, symlink, or
|
||||
concurrent declaration edit rejects the batch. Repeating a completed enrollment
|
||||
makes no changes. Filesystem errors during the write phase can leave a partial
|
||||
batch; rerun after correcting the error. This is not a filesystem transaction.
|
||||
|
||||
Only `.circleci/config.yml` and `.qqq-ci.yml` are changed. The tool does not delete
|
||||
other workflows, infer publication from repository names, or enroll unknown
|
||||
custom pipelines. Their behavior must first be represented by a central profile.
|
||||
After committing and qualifying the exact source, apply the shared
|
||||
[branch enforcement tool](branch-enforcement.md) to supported gate profiles.
|
||||
|
||||
This command provides batch source conversion. Remote discovery, signed PR
|
||||
submission, merge reconciliation and scheduled enrollment are separate remaining
|
||||
work; local conversion alone does not prove fleet deployment or release success.
|
||||
@@ -0,0 +1,105 @@
|
||||
"""Batch enrollment preserves policy and rejects unsafe or unknown declarations."""
|
||||
from pathlib import Path
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from unittest import mock
|
||||
|
||||
import yaml
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'tools'))
|
||||
import enroll_consumers as enrollment
|
||||
|
||||
|
||||
class EnrollmentTests(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.temp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.temp.cleanup)
|
||||
self.root = Path(self.temp.name)
|
||||
|
||||
def legacy(self, name):
|
||||
root = self.root / name
|
||||
(root / '.circleci').mkdir(parents=True)
|
||||
config = {'version': 2.1, 'orbs': {'qqq-orb': 'kingsrook/qqq-orb@0.5.0'},
|
||||
'workflows': {'verify': {'jobs': [{'qqq-orb/mvn_test_only': {}}]}}}
|
||||
(root / '.circleci/config.yml').write_text(yaml.safe_dump(config), encoding='utf-8')
|
||||
return {'checkout': str(root), 'default_branch': 'main'}
|
||||
|
||||
def canonical(self, profile):
|
||||
target = self.legacy(profile)
|
||||
root = Path(target['checkout'])
|
||||
data = {'profile': profile, 'orb_version': '0.7.4', 'default_branch': 'main'}
|
||||
(root / '.qqq-ci.yml').write_text(yaml.safe_dump(data), encoding='utf-8')
|
||||
(root / '.circleci/config.yml').write_text(yaml.safe_dump(
|
||||
enrollment.rollout.standard.canonical_caller(profile, '0.7.4')), encoding='utf-8')
|
||||
return target
|
||||
|
||||
def test_mixed_fleet_preview_write_and_idempotence(self):
|
||||
legacy = self.legacy('legacy')
|
||||
targets = [legacy] + [self.canonical(p) for p in enrollment.rollout.standard.PROFILE_PARAMETERS]
|
||||
preview = enrollment.enroll(targets, '0.8')
|
||||
self.assertTrue(all(item['changed'] for item in preview))
|
||||
self.assertFalse((Path(legacy['checkout']) / '.qqq-ci.yml').exists())
|
||||
result = enrollment.enroll(targets, '0.8', write=True)
|
||||
self.assertEqual(1, sum(item['enrollment'] for item in result))
|
||||
data = yaml.safe_load((Path(legacy['checkout']) / '.qqq-ci.yml').read_text())
|
||||
self.assertFalse(any(data['publish'].values()))
|
||||
self.assertEqual('all', data['test_branch_policy'])
|
||||
self.assertTrue(all(not item['changed'] for item in enrollment.enroll(targets, '0.8', write=True)))
|
||||
|
||||
def test_unknown_orchestration_rejects_entire_batch(self):
|
||||
good, bad = self.legacy('good'), self.legacy('bad')
|
||||
path = Path(bad['checkout']) / '.circleci/config.yml'
|
||||
path.write_text(path.read_text() + '\njobs: {custom: {steps: [checkout]}}\n')
|
||||
original = (Path(good['checkout']) / '.circleci/config.yml').read_bytes()
|
||||
with self.assertRaises(ValueError):
|
||||
enrollment.enroll([good, bad], '0.8', write=True)
|
||||
self.assertEqual(original, (Path(good['checkout']) / '.circleci/config.yml').read_bytes())
|
||||
self.assertFalse((Path(good['checkout']) / '.qqq-ci.yml').exists())
|
||||
|
||||
def test_duplicate_targets_and_wrong_default_reject_before_write(self):
|
||||
target = self.canonical('core')
|
||||
for targets in ([target, target], [{**target, 'default_branch': 'develop'}]):
|
||||
with self.assertRaises(ValueError):
|
||||
enrollment.enroll(targets, '0.8', write=True)
|
||||
self.assertEqual('0.7.4', yaml.safe_load((Path(target['checkout']) / '.qqq-ci.yml').read_text())['orb_version'])
|
||||
|
||||
def test_invalid_manifest_and_unstable_versions_rejected(self):
|
||||
target = self.canonical('qbit')
|
||||
path = Path(target['checkout']) / '.qqq-ci.yml'
|
||||
path.write_text(path.read_text() + '\nunknown_policy: true\n')
|
||||
for version in ('0.8', 'dev:snapshot', 'latest', 0.8):
|
||||
with self.assertRaises(ValueError):
|
||||
enrollment.enroll([target], version, write=True)
|
||||
|
||||
def test_drift_after_preflight_is_not_overwritten(self):
|
||||
target = self.legacy('drift')
|
||||
path = Path(target['checkout']) / '.circleci/config.yml'
|
||||
original_plan = enrollment.plan
|
||||
|
||||
def changed_plan(*args):
|
||||
result = original_plan(*args)
|
||||
path.write_bytes(b'concurrent edit\n')
|
||||
return result
|
||||
|
||||
with mock.patch.object(enrollment, 'plan', side_effect=changed_plan):
|
||||
with self.assertRaises(ValueError):
|
||||
enrollment.enroll([target], '0.8', write=True)
|
||||
self.assertEqual(b'concurrent edit\n', path.read_bytes())
|
||||
self.assertFalse((Path(target['checkout']) / '.qqq-ci.yml').exists())
|
||||
|
||||
def test_manifest_symlink_is_rejected(self):
|
||||
target = self.legacy('redirect')
|
||||
outside = self.root / 'outside.yml'
|
||||
outside.write_text('untouched\n')
|
||||
try:
|
||||
(Path(target['checkout']) / '.qqq-ci.yml').symlink_to(outside)
|
||||
except OSError as error:
|
||||
self.skipTest('Symlink creation unavailable: ' + str(error))
|
||||
with self.assertRaises(ValueError):
|
||||
enrollment.enroll([target], '0.8', write=True)
|
||||
self.assertEqual('untouched\n', outside.read_text())
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
unittest.main()
|
||||
@@ -0,0 +1,101 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Enroll a batch of audited consumers; preview by default, write with --write.
|
||||
|
||||
Existing canonical profiles retain their manifests. Legacy QBits use the shared
|
||||
policy inference. Unknown orchestration is rejected before any checkout changes.
|
||||
"""
|
||||
import argparse
|
||||
import json
|
||||
from pathlib import Path
|
||||
import re
|
||||
import tempfile
|
||||
|
||||
import yaml
|
||||
|
||||
import rollout_version as rollout
|
||||
import standardize_qbit as qbit
|
||||
|
||||
|
||||
def declaration(root, relative):
|
||||
"""Reject redirected declarations, including symlinked parent directories."""
|
||||
path = root / relative
|
||||
current = path
|
||||
while current != root:
|
||||
if current.is_symlink():
|
||||
raise ValueError('CI declarations must not use symlinks')
|
||||
current = current.parent
|
||||
if not path.resolve().is_relative_to(root):
|
||||
raise ValueError('CI declarations must remain inside the checkout')
|
||||
return path
|
||||
|
||||
|
||||
def plan(target, version):
|
||||
"""Preserve explicit publication policy and validate generated declarations."""
|
||||
if not isinstance(target, dict) or set(target) != {'checkout', 'default_branch'}:
|
||||
raise ValueError('Each target requires checkout and observed default_branch')
|
||||
if target['default_branch'] not in ('main', 'develop'):
|
||||
raise ValueError('Unsupported default branch')
|
||||
root = Path(target['checkout']).resolve(strict=True)
|
||||
config = declaration(root, '.circleci/config.yml')
|
||||
manifest = declaration(root, '.qqq-ci.yml')
|
||||
if manifest.exists():
|
||||
data = rollout.standard.load_yaml(manifest.read_text(encoding='utf-8'))
|
||||
if not isinstance(data, dict) or data.get('default_branch') != target['default_branch']:
|
||||
raise ValueError('Observed default branch differs from manifest')
|
||||
return {**rollout.plan(root, version), 'enrollment': False}
|
||||
original = config.read_bytes()
|
||||
data = qbit.infer_manifest(rollout.standard.load_yaml(original.decode('utf-8')),
|
||||
version, target['default_branch'])
|
||||
caller = rollout.standard.canonical_caller(data['profile'], version,
|
||||
release_tag_policy=data['release_tag_policy'], publish_feature=data['publish'].get('feature', False))
|
||||
config_raw = yaml.safe_dump(caller, sort_keys=False)
|
||||
manifest_raw = yaml.safe_dump(data, sort_keys=False)
|
||||
rollout.standard.validate(config_raw, manifest_raw, version)
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
temporary_manifest = Path(directory) / 'manifest.yml'
|
||||
temporary_manifest.write_text(manifest_raw, encoding='utf-8')
|
||||
rollout.pipeline.load_manifest(temporary_manifest, version)
|
||||
return {'checkout': str(root), 'profile': data['profile'], 'from': None,
|
||||
'to': version, 'enrollment': True,
|
||||
'files': [(config, original, config_raw.encode('utf-8')),
|
||||
(manifest, None, manifest_raw.encode('utf-8'))]}
|
||||
|
||||
|
||||
def enroll(targets, version, write=False):
|
||||
"""Validate the whole batch before writing; repeat applications are no-ops."""
|
||||
if not isinstance(version, str) or not re.fullmatch(r'\d+\.\d+(?:\.\d+)?', version):
|
||||
raise ValueError('Enrollment requires a stable minor track or exact patch')
|
||||
if not isinstance(targets, list) or not targets:
|
||||
raise ValueError('A nonempty target list is required')
|
||||
plans = [plan(target, version) for target in targets]
|
||||
if len({item['checkout'] for item in plans}) != len(plans):
|
||||
raise ValueError('Each checkout may appear only once')
|
||||
if write:
|
||||
for item in plans:
|
||||
for path, original, replacement in item['files']:
|
||||
declaration(Path(item['checkout']), path.relative_to(item['checkout']))
|
||||
current = path.read_bytes() if path.exists() else None
|
||||
if current != original:
|
||||
raise ValueError('Declaration changed after preflight')
|
||||
for item in plans:
|
||||
for path, original, replacement in item['files']:
|
||||
if replacement != original:
|
||||
path.write_bytes(replacement)
|
||||
return [{**{key: value for key, value in item.items() if key != 'files'},
|
||||
'changed': any(old != new for _, old, new in item['files']),
|
||||
'written': write} for item in plans]
|
||||
|
||||
|
||||
def main():
|
||||
"""Read one fleet target file and emit an auditable result."""
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument('targets', type=Path)
|
||||
parser.add_argument('--orb-version', required=True)
|
||||
parser.add_argument('--write', action='store_true')
|
||||
args = parser.parse_args()
|
||||
print(json.dumps(enroll(json.loads(args.targets.read_text(encoding='utf-8')),
|
||||
args.orb_version, args.write), indent=2))
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
Reference in new issue
Block a user