Compare commits

...
Author SHA1 Message Date
james.maesandCodex 3afce45e69 ci: submit enrollment with GitHub-signed API commits
Co-Authored-By: Codex <noreply@openai.com>
2026-10-21 20:15:30 -05:00
3 changed files with 226 additions and 169 deletions

No files matched your search

+128 -119
View File
@@ -1,119 +1,128 @@
# Batch consumer enrollment # Batch consumer enrollment
Use one target file for canonical consumers of every supported Circle profile and Use one target file for canonical consumers of every supported Circle profile and
legacy QBits whose jobs and publication filters the shared converter recognizes: legacy QBits whose jobs and publication filters the shared converter recognizes:
```json ```json
[ [
{"checkout": "/work/qbit-example", "default_branch": "main"}, {"checkout": "/work/qbit-example", "default_branch": "main"},
{"checkout": "/work/qqq", "default_branch": "develop"} {"checkout": "/work/qqq", "default_branch": "develop"}
] ]
``` ```
The branch values must come from repository inventory. Run on clean isolated The branch values must come from repository inventory. Run on clean isolated
checkouts of the branches being migrated. checkouts of the branches being migrated.
```sh ```sh
python tools/enroll_consumers.py targets.json --orb-version 0.8 python tools/enroll_consumers.py targets.json --orb-version 0.8
python tools/enroll_consumers.py targets.json --orb-version 0.8 --write python tools/enroll_consumers.py targets.json --orb-version 0.8 --write
``` ```
The command validates the entire batch before writing. Existing manifests keep The command validates the entire batch before writing. Existing manifests keep
all publication and profile options; only the managed orb version changes. all publication and profile options; only the managed orb version changes.
Recognized legacy QBits receive the canonical caller and inferred publication Recognized legacy QBits receive the canonical caller and inferred publication
policy. An unknown job, filter, profile option, duplicate target, symlink, or policy. An unknown job, filter, profile option, duplicate target, symlink, or
concurrent declaration edit rejects the batch. Repeating a completed enrollment concurrent declaration edit rejects the batch. Repeating a completed enrollment
makes no changes. Filesystem errors during the write phase can leave a partial 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. 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 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 other workflows, infer publication from repository names, or enroll unknown
custom pipelines. Their behavior must first be represented by a central profile. custom pipelines. Their behavior must first be represented by a central profile.
After committing and qualifying the exact source, apply the shared After committing and qualifying the exact source, apply the shared
[branch enforcement tool](branch-enforcement.md) to supported gate profiles. [branch enforcement tool](branch-enforcement.md) to supported gate profiles.
This command provides batch source conversion. Use the coordinator below for remote signed submissions. Local conversion alone does not prove fleet deployment or release success. This command provides batch source conversion. Use the coordinator below for remote signed submissions. Local conversion alone does not prove fleet deployment or release success.
## Remote signed submissions ## Remote signed submissions
Supply observed current branches, without cloning each repository yourself: Supply observed current branches, without cloning each repository yourself:
```json ```json
[ [
{"repository": "QRun-IO/qbit-example", "branch": "main"}, {"repository": "QRun-IO/qbit-example", "branch": "main"},
{"repository": "QRun-IO/qqq", "branch": "develop"} {"repository": "QRun-IO/qqq", "branch": "develop"}
] ]
``` ```
```sh ```sh
python tools/reconcile_enrollment.py --targets remote-targets.json --orb-version 0.8 --output plan.json python tools/reconcile_enrollment.py --targets remote-targets.json --orb-version 0.8 --output plan.json
python tools/reconcile_enrollment.py --targets remote-targets.json --orb-version 0.8 --output result.json --apply python tools/reconcile_enrollment.py --targets remote-targets.json --orb-version 0.8 --output result.json --apply
``` ```
Use existing `gh` authentication, GitHub SSH access, Git author identity and a Use existing `gh` authentication with repository write access. The coordinator
working Git signing configuration. The coordinator never installs credentials never installs credentials or changes authentication. Every target is inspected
or changes authentication. Every target is inspected at an immutable head and at an immutable head and validated before any remote mutation. No repository
validated before any remote mutation. Only changed targets are cloned. A moved clone, SSH key or local signing key is required. A moved target stops submission;
target stops submission; refresh the plan instead of overwriting it. refresh the plan instead of overwriting it.
An automation branch derives from the source commit and proposed declarations. An automation branch derives from the source commit and proposed declarations.
The coordinator signs its commit, pushes without force, verifies the remote The coordinator creates the branch at the observed base and uses GitHub's
signature, parent, exact changed paths and declaration bytes, then opens a PR. `createCommitOnBranch` API with `expectedHeadOid` for an atomic append. GitHub
An interrupted push or PR creation can be resumed with the same invocation: signs the commit when supported by the authenticated identity; the coordinator
matching signed branches and PRs are reused. A mismatched branch is rejected. requires remote signature verification, exact parent, changed paths and
Closed existing PRs are reported as existing; they are not silently reopened. declaration bytes before opening a PR. It never force-updates a branch.
Reports include repository, branch, immutable head and submission URL, without An interrupted branch creation, commit or PR creation can be resumed:
embedding declaration contents or credentials. Keep the report if a later target an existing branch still at the planned base receives the missing commit;
fails; earlier valid submissions remain intact. matching signed branches and PRs are reused. A mismatched branch is rejected.
Closed existing PRs are reported as existing; they are not silently reopened.
This handles remote target lists and signed submissions. Organization discovery is described below. Qualification-aware merging and classic branch enforcement are described below; scheduling and ruleset reconciliation remain separate work. A submitted PR is not a completed migration. Unknown profiles and Reports include repository, branch, immutable head and submission URL, without
native workflows require their own central conversion, not deletion by this tool. embedding declaration contents or credentials. Keep the report if a later target
fails; earlier valid submissions remain intact.
## Organization discovery
API permission, signature or commit-conflict failures stop the run. A timeout
The coordinator can select observed current branches directly from GitHub: can occur after GitHub accepted a mutation, so inspect remote state or repeat
the same invocation; do not create a different automation branch to retry.
```sh See [GitHub commit API documentation](https://docs.github.com/en/graphql/reference/commits#createcommitonbranch).
python tools/reconcile_enrollment.py --organization QRun-IO --orb-version 0.8 --output organization-plan.json
python tools/reconcile_enrollment.py --organization QRun-IO --orb-version 0.8 --output organization-result.json --apply This handles remote target lists and signed submissions. Organization discovery is described below. Qualification-aware merging and classic branch enforcement are described below; scheduling and ruleset reconciliation remain separate work. A submitted PR is not a completed migration. Unknown profiles and
``` native workflows require their own central conversion, not deletion by this tool.
Repository and branch inventories are paginated. Only existing main/develop ## Organization discovery
branches are considered; historical release branches are excluded. Archived
repositories and the orb's own bootstrap repository are reported separately. The coordinator can select observed current branches directly from GitHub:
Each supported branch receives the same immutable preflight as explicit targets.
Unknown workflows, missing entrypoints, unsupported branch layouts and unavailable ```sh
APIs stay `unresolved` in the output. They are never counted as conforming or python tools/reconcile_enrollment.py --organization QRun-IO --orb-version 0.8 --output organization-plan.json
silently converted. No-CI and native-only repositories may therefore appear as python tools/reconcile_enrollment.py --organization QRun-IO --orb-version 0.8 --output organization-result.json --apply
unresolved here; use the estate auditor for their separate policy classification. ```
Discovery finishes before any submission. `--apply` processes qualified plans Repository and branch inventories are paginated. Only existing main/develop
and retains unresolved entries for follow-up; one unsupported repository does branches are considered; historical release branches are excluded. Archived
not prevent independent valid submissions. An explicit `--targets` batch keeps repositories and the orb's own bootstrap repository are reported separately.
its stricter behavior: any preflight failure stops the whole batch. By default neither mode merges PRs or changes branch protections. Use the explicit completion flags below. Each supported branch receives the same immutable preflight as explicit targets.
Unknown workflows, missing entrypoints, unsupported branch layouts and unavailable
## Qualification and enforcement APIs stay `unresolved` in the output. They are never counted as conforming or
silently converted. No-CI and native-only repositories may therefore appear as
```sh unresolved here; use the estate auditor for their separate policy classification.
python tools/reconcile_enrollment.py --targets remote-targets.json --orb-version 0.8 --output result.json --apply --merge-ready --enforce
``` Discovery finishes before any submission. `--apply` processes qualified plans
and retains unresolved entries for follow-up; one unsupported repository does
Both flags require `--apply` and are optional. `--merge-ready` revalidates the not prevent independent valid submissions. An explicit `--targets` batch keeps
signed submission, exact parent/files/content and current base, requires successful its stricter behavior: any preflight failure stops the whole batch. By default neither mode merges PRs or changes branch protections. Use the explicit completion flags below.
CircleCI-app `setup` and `verify` checks and every advertised latest check/status,
then requests a normal exact-head squash merge. It never uses admin override or ## Qualification and enforcement
force pushes. The resulting signed merge must have the qualified source tree.
Pending/failed checks and changed bases are reported without merging. Repeated ```sh
runs can advance the same PR once checks complete; there is no polling loop that python tools/reconcile_enrollment.py --targets remote-targets.json --orb-version 0.8 --output result.json --apply --merge-ready --enforce
holds a CI executor open. ```
`--enforce` independently checks the actual current target branch, which must Both flags require `--apply` and are optional. `--merge-ready` revalidates the
pass its own orb gates before shared classic protection enforcement. Existing signed submission, exact parent/files/content and current base, requires successful
protections and other required checks are preserved. Supported gate profiles are CircleCI-app `setup` and `verify` checks and every advertised latest check/status,
QBit, Core, frontend-core, frontend-material and repository-policy. Other profiles then requests a normal exact-head squash merge. It never uses admin override or
remain explicitly unsupported for completion even when source enrollment works. force pushes. The resulting signed merge must have the qualified source tree.
Existing active repository rulesets with app-bound gates and no bypass actors are verified without writes. Unsupported or incomplete rulesets remain unresolved; none are rewritten or layered with classic protection. API/plan restrictions remain visible. Pending/failed checks and changed bases are reported without merging. Repeated
runs can advance the same PR once checks complete; there is no polling loop that
A merged source update and an enforced branch are separate reported outcomes. holds a CI executor open.
Neither proves artifact publication or deployment. Scheduling and ruleset
reconciliation remain outstanding. `--enforce` independently checks the actual current target branch, which must
pass its own orb gates before shared classic protection enforcement. Existing
protections and other required checks are preserved. Supported gate profiles are
QBit, Core, frontend-core, frontend-material and repository-policy. Other profiles
remain explicitly unsupported for completion even when source enrollment works.
Existing active repository rulesets with app-bound gates and no bypass actors are verified without writes. Unsupported or incomplete rulesets remain unresolved; none are rewritten or layered with classic protection. API/plan restrictions remain visible.
A merged source update and an enforced branch are separate reported outcomes.
Neither proves artifact publication or deployment. Scheduling and ruleset
reconciliation remain outstanding.
+53 -27
View File
@@ -118,41 +118,67 @@ class ReconcileTests(unittest.TestCase):
self.assertEqual('submitted', result['state']) self.assertEqual('submitted', result['state'])
self.assertEqual([['gh', 'pr', 'create']], seen) self.assertEqual([['gh', 'pr', 'create']], seen)
def test_new_submission_requires_signed_commit_and_never_force_pushes(self): def test_new_api_submission_is_atomic_and_exact(self):
plan = self.plan() plan = self.plan()
committed = False mutations = []
seen = []
def request(path, missing=False): def request(path, missing=False):
if '/git/ref/' in path: if '/git/ref/' in path:
return None return None
if '/pulls?' in path:
return []
return self.submission_api(plan, path, missing) return self.submission_api(plan, path, missing)
def command(args, cwd=None): def mutate(path, payload):
nonlocal committed mutations.append((path, payload))
seen.append(args) return {'data': {'createCommitOnBranch': {'commit': {'oid': self.new}}}}
if args[:2] == ['git', 'clone']:
root = Path(args[-1])
(root / '.circleci').mkdir(parents=True)
for name, data in self.sources.items():
(root / name).write_bytes(data)
elif args[:2] == ['git', 'rev-parse']:
return self.new if committed else self.head
elif args[:2] == ['git', 'commit']:
self.assertIn('-S', args)
for name in remote.PATHS:
self.assertEqual(plan['replacements'][name], (cwd / name).read_bytes())
committed = True
elif args[:3] == ['gh', 'pr', 'create']:
return 'https://github.com/QRun-IO/example/pull/3'
return ''
with mock.patch.object(remote, 'api', side_effect=request), mock.patch.object(remote, 'command', side_effect=command): with mock.patch.object(remote, 'api', side_effect=request), mock.patch.object(remote, 'mutation', side_effect=mutate), mock.patch.object(remote, 'command') as command:
self.assertEqual('submitted', remote.apply(plan)['state']) self.assertEqual('existing-pr', remote.apply(plan)['state'])
pushes = [args for args in seen if args[:2] == ['git', 'push']] command.assert_not_called()
self.assertEqual([['git', 'push', 'origin', 'HEAD:refs/heads/' + plan['automation_branch']]], pushes) self.assertEqual(('repos/' + self.repo + '/git/refs', {'ref': 'refs/heads/' + plan['automation_branch'], 'sha': self.head}), mutations[0])
commit = mutations[1][1]['variables']['input']
self.assertEqual(self.head, commit['expectedHeadOid'])
self.assertEqual({'repositoryNameWithOwner': self.repo, 'branchName': plan['automation_branch']}, commit['branch'])
self.assertEqual(plan['replacements'], {item['path']: base64.b64decode(item['contents']) for item in commit['fileChanges']['additions']})
def test_base_only_branch_resumes_without_creating_another_ref(self):
plan = self.plan()
result = {'data': {'createCommitOnBranch': {'commit': {'oid': self.new}}}}
with mock.patch.object(remote, 'api', return_value={'commit': {'sha': self.head}}), mock.patch.object(remote, 'mutation', return_value=result) as mutation:
self.assertEqual(self.new, remote.signed_api_commit(plan, {'object': {'sha': self.head}}))
self.assertEqual(1, mutation.call_count)
self.assertEqual('graphql', mutation.call_args.args[0])
def test_existing_completed_branch_is_not_mutated(self):
with mock.patch.object(remote, 'mutation') as mutation:
self.assertEqual(self.new, remote.signed_api_commit(self.plan(), {'object': {'sha': self.new}}))
mutation.assert_not_called()
def test_target_drift_prevents_commit_on_base_only_branch(self):
plan = self.plan()
with mock.patch.object(remote, 'api', return_value={'commit': {'sha': 'c' * 40}}), mock.patch.object(remote, 'mutation') as mutation:
with self.assertRaises(ValueError):
remote.signed_api_commit(plan, {'object': {'sha': self.head}})
mutation.assert_not_called()
def test_graphql_errors_fail_closed(self):
response = mock.Mock(returncode=0, stdout='{"errors": [{"message": "conflict"}]}')
with mock.patch.object(remote.subprocess, 'run', return_value=response):
with self.assertRaises(ValueError):
remote.mutation('graphql', {})
def test_unsigned_api_commit_cannot_create_pr(self):
plan = self.plan()
def request(path, missing=False):
if '/git/ref/' in path:
return {'object': {'sha': self.head}}
value = self.submission_api(plan, path, missing)
if '/commits/' in path:
value['commit']['verification']['verified'] = False
return value
with mock.patch.object(remote, 'api', side_effect=request), mock.patch.object(remote, 'mutation', return_value={'data': {'createCommitOnBranch': {'commit': {'oid': self.new}}}}), mock.patch.object(remote, 'command') as command:
with self.assertRaises(ValueError):
remote.apply(plan)
command.assert_not_called()
if __name__ == '__main__': if __name__ == '__main__':
+45 -23
View File
@@ -50,6 +50,50 @@ def content(repo, path, head):
return base64.b64decode(item['content']) return base64.b64decode(item['content'])
def mutation(path, payload):
"""Use the existing gh identity; never print credentials or response bodies."""
result = subprocess.run(['gh', 'api', path, '--method', 'POST', '--input', '-'],
input=json.dumps(payload), capture_output=True,
text=True, encoding='utf-8', timeout=60)
if result.returncode:
raise ValueError('GitHub mutation failed; inspect remote state before retrying')
try:
data = json.loads(result.stdout)
except ValueError:
raise ValueError('Invalid GitHub mutation response') from None
if not isinstance(data, dict) or data.get('errors'):
raise ValueError('GitHub mutation did not succeed')
return data
def signed_api_commit(plan, ref):
"""Resume a base-only branch; append atomically without local Git/SSH keys."""
repo, branch, base = plan['repository'], plan['automation_branch'], plan['head']
if ref is None:
mutation(f'repos/{repo}/git/refs', {'ref': 'refs/heads/' + branch, 'sha': base})
elif ref['object']['sha'] != base:
return ref['object']['sha']
if api(f'repos/{repo}/branches/{plan["branch"]}')['commit']['sha'] != base:
raise ValueError('Target branch moved before submission')
additions = [{'path': path, 'contents': base64.b64encode(plan['replacements'][path]).decode('ascii')}
for path in PATHS if plan['originals'][path] != plan['replacements'][path]]
result = mutation('graphql', {
'query': 'mutation($input: CreateCommitOnBranchInput!) { createCommitOnBranch(input: $input) { commit { oid } } }',
'variables': {'input': {
'branch': {'repositoryNameWithOwner': repo, 'branchName': branch},
'expectedHeadOid': base,
'message': {'headline': 'ci: enroll in the shared QQQ orb',
'body': 'Co-Authored-By: Codex <noreply@openai.com>'},
'fileChanges': {'additions': additions}}}})
try:
head = result['data']['createCommitOnBranch']['commit']['oid']
except (KeyError, TypeError):
raise ValueError('GitHub commit response is incomplete') from None
if not isinstance(head, str) or not re.fullmatch(r'[0-9a-f]{40}', head):
raise ValueError('GitHub commit response has no valid SHA')
return head
def inspect(target, version): def inspect(target, version):
"""Resolve observed repository identity and reuse the shared enrollment planner.""" """Resolve observed repository identity and reuse the shared enrollment planner."""
if not isinstance(target, dict) or set(target) != {'repository', 'branch'}: if not isinstance(target, dict) or set(target) != {'repository', 'branch'}:
@@ -103,29 +147,7 @@ def apply(plan):
if api(f'repos/{repo}/branches/{plan["branch"]}')['commit']['sha'] != plan['head']: if api(f'repos/{repo}/branches/{plan["branch"]}')['commit']['sha'] != plan['head']:
raise ValueError('Target branch changed after preflight') raise ValueError('Target branch changed after preflight')
ref = api(f'repos/{repo}/git/ref/heads/{branch}', missing=True) ref = api(f'repos/{repo}/git/ref/heads/{branch}', missing=True)
if ref is None: head = signed_api_commit(plan, ref)
with tempfile.TemporaryDirectory() as directory:
root = Path(directory) / 'checkout'
command(['git', 'clone', '-c', 'core.autocrlf=false', '--depth', '1', '--single-branch', '--branch', plan['branch'],
f'git@github.com:{repo}.git', str(root)])
if command(['git', 'rev-parse', 'HEAD'], root) != plan['head']:
raise ValueError('Target branch moved before checkout')
for path in PATHS:
target = enroll_consumers.declaration(root, path)
current = target.read_bytes() if target.exists() else None
if current != plan['originals'][path]:
raise ValueError('Checkout differs from immutable preflight')
target.write_bytes(plan['replacements'][path])
command(['git', 'add', '--', *PATHS], root)
command(['git', 'diff', '--cached', '--check'], root)
command(['git', 'commit', '-S', '-m', 'ci: enroll in the shared QQQ orb', '-m',
'Co-Authored-By: Codex <noreply@openai.com>'], root)
head = command(['git', 'rev-parse', 'HEAD'], root)
if api(f'repos/{repo}/branches/{plan["branch"]}')['commit']['sha'] != plan['head']:
raise ValueError('Target branch moved before submission')
command(['git', 'push', 'origin', f'HEAD:refs/heads/{branch}'], root)
else:
head = ref['object']['sha']
verify_submission(plan, head) verify_submission(plan, head)
pulls = api(f'repos/{repo}/pulls?state=all&head={repo.split("/")[0]}:{branch}&base={plan["branch"]}') pulls = api(f'repos/{repo}/pulls?state=all&head={repo.split("/")[0]}:{branch}&base={plan["branch"]}')
if pulls: if pulls: