Merge pull request #999 from iflytek/feat/issue994-migration-preflight-20261021
Some checks are pending
Deploy Docs / build (push) Waiting to run
Deploy Docs / Deploy (push) Blocked by required conditions
Security / Dependency Review (push) Waiting to run
Security / CodeQL (java-kotlin) (push) Waiting to run
Security / CodeQL (javascript-typescript) (push) Waiting to run
Security / CodeQL (python) (push) Waiting to run

ci(db): warn about migration number collisions across open PRs
This commit is contained in:
XiaoSeS 2026-10-21 18:22:26 +08:00 • committed by GitHub
commit 4811b96129
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 430 additions and 0 deletions

View file

@ -20,5 +20,15 @@ jobs:
java-version: 21
cache: maven
- name: Set up Go for integration tests
uses: actions/setup-go@v5
with:
go-version-file: github-sync-go/go.mod
cache-dependency-path: github-sync-go/go.mod
- name: Compile Go integration test dependencies
working-directory: github-sync-go
run: go test ./internal/worker -run '^$'
- name: Backend tests
run: cd server && ./mvnw -B test

View file

@ -0,0 +1,45 @@
name: Migration Preflight
on:
pull_request_target:
types: [opened, reopened, synchronize, closed, edited, ready_for_review]
schedule:
- cron: '17 */6 * * *'
workflow_dispatch:
permissions:
contents: read
pull-requests: read
concurrency:
group: migration-preflight
cancel-in-progress: true
jobs:
preflight:
name: Advisory Flyway version scan
runs-on: ubuntu-latest
timeout-minutes: 10
continue-on-error: true
steps:
# Never check out a PR head or run SQL. This workflow only runs trusted
# default-branch code, including for pull requests from forks.
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
id: checkout
continue-on-error: true
with:
ref: ${{ github.event.repository.default_branch }}
persist-credentials: false
- name: Summarize open PR migration versions
id: scan
if: steps.checkout.outcome == 'success'
continue-on-error: true
env:
GITHUB_TOKEN: ${{ github.token }}
run: python3 scripts/migration-preflight.py
- name: Report unavailable scan
if: ${{ always() && (steps.checkout.outcome != 'success' || steps.scan.outcome != 'success') }}
run: |
printf '%s\n' '## Flyway migration preflight' '' '**Warning: scan unavailable. No clearance issued.** Check this workflow run for checkout, runtime or timeout failures.' >> "$GITHUB_STEP_SUMMARY"

View file

@ -30,6 +30,7 @@ on:
- '.github/workflows/publish-chart.yml'
- '.github/workflows/security.yml'
- '.github/workflows/pr-scripts.yml'
- '.github/workflows/migration-preflight.yml'
- '**/*.py'
permissions:
@ -66,3 +67,4 @@ jobs:
- run: bash scripts/tests/server-image-compat-test.sh
- run: bash scripts/tests/workflow-security-test.sh
- run: python3 -m unittest discover -s scripts/tests -p 'test_deepwiki_workflow.py' -v
- run: python3 -m unittest discover -s scripts/tests -p 'test_migration_preflight.py' -v

View file

@ -107,3 +107,33 @@ Do not open public issues for suspected security vulnerabilities.
Use GitHub Security Advisories or your internal security process to report them
privately to the maintainers.
## Flyway migration version advisory
The **Migration Preflight** workflow reads file metadata for all open PRs on PR
changes, every six hours, or via **Actions → Migration Preflight → Run workflow**.
See its Actions run summary for migration numbers introduced by more than one PR.
It checks `server/skillhub-app/src/main/resources/db/migration/V<n>__*.sql` additions,
including renames that introduce a different migration number. Pure renames with
the same number, modified/deleted migrations and conflicts with migrations already
merged into the base branch are outside this advisory's scope.
This is a snapshot and a non-blocking warning, not a reservation or merge gate.
If a scan is incomplete (for example API permissions, file-list truncation or a
PR changing during collection), its summary says so; it must not be interpreted
as confirmation of no conflict. The script exits nonzero on an incomplete scan;
the workflow keeps this advisory and explicitly adds an unavailable-scan warning. PRs with 3,000 or more changed files are conservatively
reported as incomplete because GitHub caps the files endpoint at 3,000 entries.
Coordinate numbering with the other PR's author, update your migration filename,
and rerun the relevant database/migration tests before merging. The workflow does
not renumber files, post comments, fetch raw SQL files or execute PR code. The
GitHub files API may include diff patches; the script ignores them and only uses
file names/status, PR numbers and revision metadata. It uses only
repository-content and pull-request read permissions and runs the default branch's
script, so workflow/script changes take effect only after merging into that branch.
Local offline regression checks (Python standard library only):
```bash
python3 -m unittest discover -s scripts/tests -p 'test_migration_preflight.py' -v
```

View file

@ -0,0 +1,143 @@
#!/usr/bin/env python3
"""Read GitHub PR file metadata and summarize possible Flyway version collisions."""
import html
import json
import os
from pathlib import Path
import re
import urllib.error
import urllib.request
MIGRATION = re.compile(
r"server/skillhub-app/src/main/resources/db/migration/V([0-9]+)__[^/]+\.sql\Z"
)
class ScanError(Exception):
pass
def version(path):
match = MIGRATION.fullmatch(path)
return int(match[1]) if match else None
def introduced_version(file):
number = version(file["filename"])
if file["status"] == "added":
return number
if file["status"] == "renamed" and version(file.get("previous_filename", "")) != number:
return number
return None
class GitHub:
def __init__(self, repository, token):
if not re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", repository):
raise ScanError("Invalid repository name")
self.base = f"https://api.github.com/repos/{repository}"
self.token = token
def get(self, path):
request = urllib.request.Request(self.base + path, headers={
"Authorization": f"Bearer {self.token}",
"Accept": "application/vnd.github+json",
"X-GitHub-Api-Version": "2022-11-28",
})
try:
with urllib.request.urlopen(request, timeout=30) as response:
return json.load(response)
except urllib.error.HTTPError as error:
raise ScanError(f"GitHub API HTTP {error.code}; scan incomplete") from error
except (urllib.error.URLError, TimeoutError, ValueError, OSError) as error:
# Do not echo server payloads, tokens, request headers or arbitrary URLs.
raise ScanError(f"GitHub API {type(error).__name__}; scan incomplete") from error
def pages(self, path, limit=None):
result = []
for page in range(1, 1001):
separator = "&" if "?" in path else "?"
batch = self.get(f"{path}{separator}per_page=100&page={page}")
if not isinstance(batch, list):
raise ScanError("Unexpected GitHub pagination response")
result.extend(batch)
if len(batch) < 100:
return result
if limit is not None and len(result) >= limit:
raise ScanError("PR files reached GitHub's 3000-file limit")
raise ScanError("Pagination safety limit reached")
def scan(api):
versions = {}
errors = []
prs = api.pages("/pulls?state=open&sort=created&direction=asc")
for pr in prs:
number = pr["number"]
try:
files = api.pages(f"/pulls/{number}/files", limit=3000)
current = api.get(f"/pulls/{number}")
if (current["head"]["sha"] != pr["head"]["sha"]
or current["base"]["sha"] != pr["base"]["sha"]
or current["state"] != "open"):
raise ScanError("PR changed during scan; rerun required")
if len(files) != current["changed_files"]:
raise ScanError("PR file list incomplete; rerun required")
for file in files:
value = introduced_version(file)
if value is not None:
versions.setdefault(value, {}).setdefault(number, []).append(file["filename"])
except ScanError as error:
errors.append(f"PR #{number}: {error}")
return {v: entries for v, entries in sorted(versions.items()) if len(entries) > 1}, errors, len(prs)
def safe(value):
# HTML text in a pre block avoids Markdown/link/table injection from filenames.
return html.escape(str(value)).replace("\r", "&#13;").replace("\n", "&#10;")
def summary(collisions, errors, count):
lines = ["## Flyway migration preflight", "",
"Advisory only: no SQL files are fetched or executed; no PR is changed.", "",
f"Open PRs discovered: {count}.", ""]
if errors:
lines += ["**Warning: scan incomplete. Absence of a reported collision is not clearance.**", "", "<pre>",
*(safe(error) for error in errors), "</pre>", ""]
if collisions:
lines += ["**Warning: migration versions introduced by multiple open PRs:**", "", "<pre>"]
for value, entries in collisions.items():
lines.append(f"V{value}")
for number, paths in sorted(entries.items()):
lines.extend(f" PR #{number}: {safe(path)}" for path in sorted(set(paths)))
lines += ["</pre>", "", "Authors should coordinate numbering and rerun migration tests before merge."]
elif not errors:
lines.append("No cross-PR version collisions found in this snapshot.")
lines += ["", "Scope: added migrations and renames introducing a different version in the application migration directory. "
"Same-version renames, modified/deleted files and conflicts with already merged migrations are not checked. "
"Concurrent PR changes can make this advisory snapshot stale.", ""]
return "\n".join(lines)
def main():
try:
api = GitHub(os.environ.get("GITHUB_REPOSITORY", ""), os.environ.get("GITHUB_TOKEN", ""))
collisions, errors, count = scan(api)
except ScanError as error:
collisions, errors, count = {}, [str(error)], 0
except (KeyError, TypeError):
collisions, errors, count = {}, ["Malformed GitHub API response; no clearance issued."], 0
report = summary(collisions, errors, count)
destination = os.environ.get("GITHUB_STEP_SUMMARY")
if destination:
with Path(destination).open("a", encoding="utf-8") as output:
output.write(report)
else:
print(report)
return 1 if errors else 0 # Workflow treats errors as advisory, never as scan clearance.
if __name__ == "__main__":
raise SystemExit(main())

View file

@ -0,0 +1,200 @@
"""Offline behavior tests for the read-only migration preflight."""
import contextlib
import importlib.util
import io
import os
import tempfile
import urllib.error
from unittest.mock import patch
from pathlib import Path
import unittest
ROOT = Path(__file__).resolve().parents[2]
spec = importlib.util.spec_from_file_location("preflight", ROOT / "scripts/migration-preflight.py")
m = importlib.util.module_from_spec(spec)
spec.loader.exec_module(m)
PREFIX = "server/skillhub-app/src/main/resources/db/migration/"
class PreflightTest(unittest.TestCase):
def test_status_and_rename_boundaries(self):
path = PREFIX + "V001__new.sql"
self.assertEqual(m.introduced_version(dict(filename=path, status="added")), 1)
for status in ("modified", "removed", "copied"):
self.assertIsNone(m.introduced_version(dict(filename=path, status=status)))
self.assertIsNone(m.introduced_version(dict(filename=path, status="renamed",
previous_filename=PREFIX + "V1__old.sql")))
self.assertEqual(m.introduced_version(dict(filename=path, status="renamed",
previous_filename=PREFIX + "V2__old.sql")), 1)
for path in ("tests/V1__fake.sql", PREFIX + "V1_2__other.sql", PREFIX + "V1__new.sql/no"):
self.assertIsNone(m.introduced_version(dict(filename=path, status="added")))
def test_multiple_collisions_sorted_and_single_pr_not_collision(self):
class API:
def pages(self, path, limit=None):
if path.startswith("/pulls?"):
return [dict(number=n, head=dict(sha=str(n)), base=dict(sha="base")) for n in (9, 2)]
return [dict(filename=PREFIX + f"V{v}__a.sql", status="added") for v in (20, 3, 3)]
def get(self, path):
return dict(head=dict(sha=path.split("/")[-1]), state="open", base=dict(sha="base"), changed_files=3)
collisions, errors, count = m.scan(API())
self.assertEqual(list(collisions), [3, 20])
self.assertEqual(errors, [])
self.assertEqual(count, 2)
report = m.summary(collisions, errors, count)
self.assertLess(report.index("PR #2"), report.index("PR #9"))
self.assertEqual(report.count("PR #2:"), 2)
def test_incomplete_never_reports_clearance(self):
report = m.summary({}, ["API HTTP 403"], 3)
self.assertIn("scan incomplete", report)
self.assertNotIn("No cross-PR", report)
def test_untrusted_filename_is_text(self):
attack = PREFIX + "V1__</pre><script>alert(1)</script>\n::error::x.sql"
report = m.summary({1: {2: [attack], 3: [PREFIX + "V1__a.sql"]}}, [], 2)
self.assertNotIn("<script>", report)
self.assertIn("&lt;script&gt;", report)
self.assertIn("&#10;", report)
def test_malformed_response_and_actual_files_cap(self):
api = m.GitHub("iflytek/skillhub", "token")
with patch.object(api, "get", return_value={"unexpected": True}):
with self.assertRaises(m.ScanError):
api.pages("/pulls")
with patch.object(api, "get", return_value=[{}] * 100) as get:
with self.assertRaises(m.ScanError):
api.pages("/pulls/1/files", limit=3000)
self.assertEqual(get.call_count, 30)
with patch.dict(os.environ, {"GITHUB_REPOSITORY": "iflytek/skillhub",
"GITHUB_STEP_SUMMARY": ""}):
with patch.object(m, "scan", side_effect=KeyError("filename")):
with contextlib.redirect_stdout(io.StringIO()) as output:
self.assertEqual(m.main(), 1)
self.assertIn("Malformed GitHub API response", output.getvalue())
self.assertNotIn("No cross-PR", output.getvalue())
def test_pagination_and_limit(self):
class API(m.GitHub):
def __init__(self):
self.calls = []
def get(self, path):
self.calls.append(path)
return [dict()] * (100 if path.endswith("&page=1") else 1)
api = API()
self.assertEqual(len(api.pages("/pulls?state=open")), 101)
self.assertEqual(api.calls[1], "/pulls?state=open&per_page=100&page=2")
with self.assertRaises(m.ScanError):
API().pages("/pulls/1/files", limit=100)
def test_single_pr_duplicates_do_not_collide(self):
class API:
def pages(self, path, limit=None):
if path.startswith("/pulls?"):
return [dict(number=1, head=dict(sha="sha"), base=dict(sha="base"))]
return [dict(filename=PREFIX + "V1__a.sql", status="added"),
dict(filename=PREFIX + "V1__b.sql", status="added")]
def get(self, path):
return dict(head=dict(sha="sha"), state="open", base=dict(sha="base"), changed_files=2)
self.assertEqual(m.scan(API()), ({}, [], 1))
def test_api_failure_retains_confirmed_collisions_and_marks_incomplete(self):
class API:
def pages(self, path, limit=None):
if path.startswith("/pulls?"):
return [dict(number=n, head=dict(sha="sha"), base=dict(sha="base")) for n in (1, 2, 3)]
if path == "/pulls/3/files":
raise m.ScanError("GitHub API HTTP 403; scan incomplete")
return [dict(filename=PREFIX + "V5__a.sql", status="added")]
def get(self, path):
return dict(head=dict(sha="sha"), state="open", base=dict(sha="base"), changed_files=1)
collisions, errors, count = m.scan(API())
self.assertEqual(list(collisions[5]), [1, 2])
self.assertIn("PR #3", errors[0])
report = m.summary(collisions, errors, count)
self.assertIn("scan incomplete", report)
self.assertIn("V5", report)
def test_changed_or_closed_pr_and_truncated_files_are_incomplete(self):
for change in (dict(head=dict(sha="changed")), dict(state="closed"), dict(base=dict(sha="changed")), dict(changed_files=2)):
class API:
def pages(self, path, limit=None):
if path.startswith("/pulls?"):
return [dict(number=1, head=dict(sha="sha"), base=dict(sha="base"))]
return [dict(filename=PREFIX + "V1__a.sql", status="added")]
def get(self, path):
return dict(dict(head=dict(sha="sha"), state="open", base=dict(sha="base"), changed_files=1), **change)
collisions, errors, _ = m.scan(API())
self.assertEqual(collisions, {})
self.assertEqual(len(errors), 1)
def test_get_uses_only_read_api_and_redacts_errors(self):
api = m.GitHub("iflytek/skillhub", "private-token")
with patch.object(m.urllib.request, "urlopen", return_value=io.BytesIO(b'[]')) as opening:
self.assertEqual(api.get("/pulls?state=open"), [])
request = opening.call_args.args[0]
self.assertEqual(request.get_method(), "GET")
self.assertEqual(request.full_url, "https://api.github.com/repos/iflytek/skillhub/pulls?state=open")
self.assertEqual(opening.call_args.kwargs["timeout"], 30)
for error in (urllib.error.HTTPError("https://secret", 403, "private-token", {}, None),
urllib.error.URLError("private-token"), TimeoutError("private-token"),
ValueError("private-token")):
with patch.object(m.urllib.request, "urlopen", side_effect=error):
with self.assertRaises(m.ScanError) as caught:
api.get("/pulls")
self.assertNotIn("private-token", str(caught.exception))
self.assertNotIn("https://secret", str(caught.exception))
with self.assertRaises(m.ScanError):
m.GitHub("owner/repo/../../other", "token")
def test_main_writes_summary_and_is_advisory_on_failure(self):
with tempfile.TemporaryDirectory() as directory:
destination = Path(directory) / "summary"
with patch.dict(os.environ, {"GITHUB_REPOSITORY": "iflytek/skillhub",
"GITHUB_TOKEN": "token", "GITHUB_STEP_SUMMARY": str(destination)}):
with patch.object(m.GitHub, "pages", side_effect=m.ScanError("API unavailable")):
self.assertEqual(m.main(), 1)
self.assertIn("scan incomplete", destination.read_text())
with patch.object(m, "scan", return_value=({}, [], 0)):
self.assertEqual(m.main(), 0)
self.assertIn("No cross-PR version collisions", destination.read_text())
def test_full_multi_page_pr_and_file_collection(self):
class API(m.GitHub):
def __init__(self):
self.calls = []
def get(self, path):
self.calls.append(path)
if path.startswith("/pulls?"):
start, end = (1, 101) if path.endswith("&page=1") else (101, 102)
return [dict(number=n, head=dict(sha="sha"), base=dict(sha="base")) for n in range(start, end)]
if "/files?" in path:
if path.endswith("&page=1"):
return [dict(filename=PREFIX + f"V{i}__a.sql", status="added") for i in range(100)]
return [dict(filename=PREFIX + "V100__a.sql", status="added")]
return dict(head=dict(sha="sha"), state="open", base=dict(sha="base"), changed_files=101)
api = API()
collisions, errors, count = m.scan(api)
self.assertEqual(count, 101)
self.assertEqual(len(collisions), 101)
self.assertEqual(len(collisions[100]), 101)
self.assertEqual(errors, [])
self.assertIn("/pulls/101/files?per_page=100&page=2", api.calls)
def test_workflow_trust_permissions_failure_fallback_and_ci_wiring(self):
workflow = (ROOT / ".github/workflows/migration-preflight.yml").read_text()
for expected in ("pull_request_target:", "schedule:", "workflow_dispatch:",
"contents: read", "pull-requests: read", "continue-on-error: true",
"ref: ${{ github.event.repository.default_branch }}", "persist-credentials: false",
"No clearance issued", "python3 scripts/migration-preflight.py"):
self.assertIn(expected, workflow)
for forbidden in ("pull_request.head", "secrets.", "pull-requests: write", "issues: write"):
self.assertNotIn(forbidden, workflow)
scripts = (ROOT / ".github/workflows/pr-scripts.yml").read_text()
self.assertIn("'.github/workflows/migration-preflight.yml'", scripts)
self.assertIn("-p 'test_migration_preflight.py'", scripts)
if __name__ == "__main__":
unittest.main()