Skip to content
Merged
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
2 changes: 2 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,5 @@ What changed, and why? Link a relevant issue if there is one.
How did you check the result? Include screenshots for visual changes and note any checks you could not run.

For dataset changes, identify the source release and rendering settings, and follow [the dataset guide](../docs/DATASET_CONTRIBUTING.md). Do not include game inputs or intermediate renders.

For dataset or deployment-tool/workflow changes, wait for `Dataset review (trusted)` on the exact PR head before merging, even when ordinary CI passes and the active map graph is unchanged.
6 changes: 3 additions & 3 deletions .github/workflows/dataset-review.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ on:
workflow_dispatch:
inputs:
pr_number:
description: PR to review (zero when bootstrapping a baseline)
description: Open or merged PR to review (zero for a baseline)
required: false
default: 0
type: number
Expand All @@ -15,12 +15,12 @@ on:
default: ''
type: string
expected_head:
description: Exact current PR head SHA (required for a PR review)
description: Exact PR head SHA (required for a PR review)
required: false
default: ''
type: string
expected_base:
description: Exact current PR base SHA (required for a PR review)
description: Exact PR base SHA (merge commit first parent for a merged PR)
required: false
default: ''
type: string
Expand Down
26 changes: 26 additions & 0 deletions docs/DATASET_CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,11 @@ candidate scripts and workflows never execute in this review. Both the PR head
and base must match the dispatch inputs, which are also recorded in the run
title. A new head or base requires a fresh review.

Run this review before merging changes to datasets, deployment tools or their
workflows, even when the active map graph is unchanged. Ordinary CI and prepared
map checks do not replace `Dataset review (trusted)`; wait for that check on the
exact PR head before merging.

For a PR, use its current head/base SHAs. Both snapshots use their own committed
Release lock:

Expand Down Expand Up @@ -239,6 +244,27 @@ This maintainer command needs Actions write access and rechecks the current PR,
CI run and trusted review immediately before retrying failed jobs. The review
workflow itself has no Actions write permission.

If a PR was merged before its trusted review ran, the same workflow can review
the merged PR. Use its original head and the merge commit's first parent as the
base, rather than the current tip of `main`:

```bash
pr=123
head_sha=$(gh api "repos/omggga/morrowind-map/pulls/$pr" --jq .head.sha)
merge_sha=$(gh api --paginate "repos/omggga/morrowind-map/issues/$pr/timeline" --jq '.[] | select(.event == "merged") | .commit_id')
base_sha=$(gh api "repos/omggga/morrowind-map/git/commits/$merge_sha" --jq '.parents[0].sha')
gh workflow run dataset-review.yml --repo omggga/morrowind-map --ref main \
-f pr_number="$pr" -f expected_head="$head_sha" -f expected_base="$base_sha"
```

Recovery requires a PR merged into canonical `main` with a two-parent merge
commit whose second parent is the exact PR head. A closed, unmerged PR, squash
merge, or mismatching head/base is rejected. The normal archive, graph, receipt
and publication checks still run; the deployment gate also checks the actual
merged snapshot. After the trusted check succeeds, rerun the failed deployment
job for that main commit only if it is still the intended production revision.
Use Actions for that retry; `dataset_review_retry` targets open PR CI runs only.

To review and publish a Release-backed baseline without a PR, use
`pr_number=0`, `bootstrap_sha=<full-main-ancestor-SHA>` and `source_mapping=[]`.
That commit must be an ancestor of the trusted tools and contain its own lock
Expand Down
30 changes: 30 additions & 0 deletions tools/deployment/dataset_review_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,36 @@ def publish_release(self, release_id: int, *, tag: str | None = None):
def get_pull(self, number: int):
return self._request(f'repos/{REPOSITORY}/pulls/{positive_id(number)}')

def get_pull_merge_sha(self, number: int) -> str:
# REST 2026-03-10 removed merge_commit_sha from PR responses. The
# canonical PR timeline still identifies the actual merged commit.
prefix = f'repos/{REPOSITORY}/issues/{positive_id(number)}/timeline'
merged = None
count = 0
for page in range(1, 12):
batch = self._request(f'{prefix}?per_page=100&page={page}')
if not isinstance(batch, list) or len(batch) > 100 or count + len(batch) > 1000:
raise DeploymentError('PR timeline count exceeds its limit')
count += len(batch)
for event in batch:
if not isinstance(event, dict) or not isinstance(event.get('event'), str):
raise DeploymentError('PR timeline contains an invalid event')
if event['event'] == 'merged':
revision = event.get('commit_id')
if merged is not None or not isinstance(revision, str) or not re.fullmatch(r'[a-f0-9]{40}', revision):
raise DeploymentError('PR timeline contains conflicting or invalid merge events')
merged = revision
if len(batch) < 100:
if merged is None:
raise DeploymentError('PR timeline does not identify a merge commit')
return merged
raise DeploymentError('PR timeline pagination exceeded its limit')

def get_commit(self, revision: str):
if not isinstance(revision, str) or not re.fullmatch(r'[a-f0-9]{40}', revision):
raise DeploymentError('Commit lookup requires a full lowercase commit SHA')
return self._request(f'repos/{REPOSITORY}/git/commits/{revision}')

def create_check(self, payload: dict):
return self._request(f'repos/{REPOSITORY}/check-runs', method='POST', body=payload)

Expand Down
28 changes: 23 additions & 5 deletions tools/deployment/dataset_review_workflow.py
Original file line number Diff line number Diff line change
Expand Up @@ -47,11 +47,29 @@ def _write(path: Path, value) -> None:

def _pull(api, number: int) -> tuple[str, str]:
pr = api.get_pull(positive_id(number))
if (not isinstance(pr, dict) or pr.get('number') != number or pr.get('state') != 'open'
or pr.get('base', {}).get('ref') != 'main'
or pr.get('base', {}).get('repo', {}).get('full_name') != REPOSITORY):
raise DeploymentError('Review requires an open PR into this repository main')
return sha(pr.get('head', {}).get('sha')), sha(pr['base'].get('sha'))
if not isinstance(pr, dict) or type(pr.get('number')) is not int or pr['number'] != number:
raise DeploymentError('Review requires a matching PR identity')
base, head_record = pr.get('base'), pr.get('head')
if (not isinstance(base, dict) or not isinstance(head_record, dict)
or base.get('ref') != 'main' or not isinstance(base.get('repo'), dict)
or base['repo'].get('full_name') != REPOSITORY):
raise DeploymentError('Review requires a PR into this repository main')
head = sha(head_record.get('sha'))
if pr.get('state') == 'open' and pr.get('merged') is False:
return head, sha(base.get('sha'))
if pr.get('state') != 'closed' or pr.get('merged') is not True:
raise DeploymentError('Review requires an open or merged PR, not an unmerged closed PR')
merge_sha = sha(api.get_pull_merge_sha(number))
merge = api.get_commit(merge_sha)
parents = merge.get('parents') if isinstance(merge, dict) else None
if (not isinstance(merge, dict) or merge.get('sha') != merge_sha
or not isinstance(parents, list) or len(parents) != 2
or not all(isinstance(parent, dict) for parent in parents)
or parents[1].get('sha') != head):
raise DeploymentError('Merged PR must identify a two-parent merge commit with its exact head')
# The live base branch may advance after merging. The deployment gate also
# binds to this immutable first parent, never to the current branch tip.
return head, sha(parents[0].get('sha'))


def freeze(*, api, pr_number: int, bootstrap_sha: str, tool_sha: str,
Expand Down
40 changes: 40 additions & 0 deletions tools/deployment/tests/test_dataset_review_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,46 @@


class ReviewAPITests(unittest.TestCase):
def test_merge_lookup_reads_the_complete_canonical_timeline(self):
api = ReleaseAPI()
merged = {'event': 'merged', 'commit_id': 'a' * 40}
first = [merged] + [{'event': 'commented'} for _ in range(99)]
with mock.patch.object(api, '_request', side_effect=[first, []]) as request:
self.assertEqual(api.get_pull_merge_sha(19), 'a' * 40)
self.assertEqual(request.call_args_list, [
mock.call('repos/omggga/morrowind-map/issues/19/timeline?per_page=100&page=1'),
mock.call('repos/omggga/morrowind-map/issues/19/timeline?per_page=100&page=2')])
with mock.patch.object(api, '_request', side_effect=[first, [merged]]):
with self.assertRaisesRegex(DeploymentError, 'conflicting'):
api.get_pull_merge_sha(19)

def test_merge_lookup_rejects_missing_invalid_or_unbounded_events(self):
api = ReleaseAPI()
for batch in (None, {}, [], [None], [{}], [{'event': 'merged'}],
[{'event': 'merged', 'commit_id': 'A' * 40}],
[{'event': 'commented'}] * 101):
with self.subTest(batch=batch), mock.patch.object(api, '_request', return_value=batch):
with self.assertRaises(DeploymentError):
api.get_pull_merge_sha(19)
with mock.patch.object(api, '_request', return_value=[{'event': 'commented'}] * 100) as request:
with self.assertRaisesRegex(DeploymentError, 'limit'):
api.get_pull_merge_sha(19)
self.assertEqual(request.call_count, 11)
with mock.patch.object(api, '_request') as request:
with self.assertRaises(DeploymentError):
api.get_pull_merge_sha(True)
request.assert_not_called()

def test_commit_lookup_uses_only_a_canonical_repository_and_full_sha(self):
api = ReleaseAPI()
with mock.patch.object(api, '_request', return_value={}) as request:
api.get_commit('a' * 40)
request.assert_called_once_with('repos/omggga/morrowind-map/git/commits/' + 'a' * 40)
for revision in ('main', '../other', 'A' * 40, None):
with self.subTest(revision=revision), self.assertRaises(DeploymentError):
api.get_commit(revision)
self.assertEqual(request.call_count, 1)

def test_source_read_redirect_never_carries_token_to_storage(self):
api = ReleaseAPI()
with mock.patch('tools.deployment.dataset_review_api._credential', return_value='credential'), \
Expand Down
81 changes: 80 additions & 1 deletion tools/deployment/tests/test_dataset_review_workflow.py
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ def setUp(self):
self.base = self.commit()
(self.root / 'README.md').write_text('Candidate documentation change.\n')
self.head = self.commit()
self.pr = {'number': 17, 'state': 'open', 'head': {'sha': self.head},
self.pr = {'number': 17, 'state': 'open', 'merged': False, 'head': {'sha': self.head},
'base': {'sha': self.base, 'ref': 'main', 'repo': {'full_name': REPOSITORY}}}
self.release = {'id': 101, 'tag_name': self.entry['releaseTag'], 'draft': False, 'immutable': True}
self.assets = []
Expand All @@ -66,6 +66,21 @@ def commit(self):
def get_pull(self, number):
return copy.deepcopy(self.pr)

def get_commit(self, revision):
return copy.deepcopy(self.merge_metadata)

def get_pull_merge_sha(self, number):
return self.merge_sha

def merge_pull(self):
merge = self.git('commit-tree', self.head + '^{tree}', '-p', self.base,
'-p', self.head, '-m', 'Merged fixture')
self.merge_metadata = {'sha': merge, 'parents': [{'sha': self.base}, {'sha': self.head}]}
self.merge_sha = merge
self.pr.update(state='closed', merged=True)
# The live branch tip is not the immutable base of the merged PR.
self.pr['base']['sha'] = 'f' * 40

def release_by_tag(self, repository, tag):
return self.release

Expand Down Expand Up @@ -145,6 +160,9 @@ def test_bootstrap_uses_its_own_committed_release_lock(self):
self.assertEqual(receipt['packages'][0]['entry'], self.entry)

def test_publication_and_durable_success_binding_follow_complete_review(self):
self.check_publication_and_binding()

def check_publication_and_binding(self):
receipt = self.prepare()
receipt_path = self.root / 'work/report/receipt.json'
binding = promote_review(receipt_path=receipt_path, receipt_sha=digest(receipt),
Expand All @@ -170,6 +188,67 @@ def test_receipt_tampering_or_wrong_attempt_prevents_publication(self):
api=self, tool_sha=self.head, run_id=123, run_attempt=attempt)
publish.assert_not_called()

def test_merged_pr_completes_review_publication_and_success_binding(self):
self.merge_pull()
self.check_publication_and_binding()
binding = json.loads(self.checks[0]['output']['text'])
self.assertEqual(binding['baseSha'], self.base)
self.assertEqual(binding['headSha'], self.head)

def test_merge_after_review_preserves_the_frozen_head_and_base(self):
receipt = self.prepare()
self.merge_pull()
binding = promote_review(receipt_path=self.root / 'work/report/receipt.json',
receipt_sha=digest(receipt), work_root=self.root / 'work-pub',
api=self, tool_sha=self.head, run_id=123, run_attempt=1)
self.assertEqual(binding['baseSha'], self.base)

def test_invalid_merge_identity_or_parents_cannot_start_review(self):
self.merge_pull()
original = copy.deepcopy(self.merge_metadata)
variants = [None, {}, dict(original, sha='a' * 40),
dict(original, parents=[]), dict(original, parents=[{'sha': self.base}]),
dict(original, parents=[{'sha': self.base}, {'sha': 'a' * 40}]),
dict(original, parents=[{'sha': 'not-a-sha'}, {'sha': self.head}]),
dict(original, parents=[{'sha': self.base}, None]),
dict(original, parents=original['parents'] + [{'sha': self.head}])]
for value in variants:
self.merge_metadata = value
with self.subTest(value=value), self.assertRaises(DeploymentError):
self.context()

def test_malformed_pr_identity_or_state_cannot_start_review(self):
original = copy.deepcopy(self.pr)
variants = [None, {}, dict(original, base=None), dict(original, head=None),
dict(original, base=dict(original['base'], repo=None)),
dict(original, merged=None), dict(original, merged='true'),
dict(original, merged=True), dict(original, state='closed')]
for value in variants:
self.pr = value
with self.subTest(value=value), self.assertRaises(DeploymentError):
self.context()

def test_closed_unmerged_pr_cannot_publish_a_prepared_review(self):
receipt = self.prepare()
self.pr.update(state='closed', merged=False)
with mock.patch('tools.deployment.dataset_review_workflow.publish_packages') as publish:
with self.assertRaises(DeploymentError):
promote_review(receipt_path=self.root / 'work/report/receipt.json',
receipt_sha=digest(receipt), work_root=self.root / 'work-pub',
api=self, tool_sha=self.head, run_id=123, run_attempt=1)
publish.assert_not_called()

def test_merge_with_a_different_base_cannot_publish_a_prepared_review(self):
receipt = self.prepare()
self.merge_pull()
self.merge_metadata['parents'][0]['sha'] = 'a' * 40
with mock.patch('tools.deployment.dataset_review_workflow.publish_packages') as publish:
with self.assertRaisesRegex(DeploymentError, 'head or base changed'):
promote_review(receipt_path=self.root / 'work/report/receipt.json',
receipt_sha=digest(receipt), work_root=self.root / 'work-pub',
api=self, tool_sha=self.head, run_id=123, run_attempt=1)
publish.assert_not_called()

def test_stale_head_or_base_fails_before_publication_and_success_check(self):
receipt = self.prepare()
self.pr['head']['sha'] = 'a' * 40
Expand Down