Handle private repos in workflow migration

llucax · llucax · commit ace7c0f30743 · 2026-03-26T14:11:59.000+01:00
Treat the docs and PyPI publish patterns in ci.yaml as optional when the
repository appears to be private, so migrations do not fail just because
those jobs were removed intentionally.

When those publish jobs are still present in a private repository, warn
with a manual step so maintainers can remove them after applying
the workflow updates.

Signed-off-by: Leandro Lucarella &lt;luca-frequenz@llucax.com&gt;
diff --git a/cookiecutter/migrate.py b/cookiecutter/migrate.py
@@ -55,6 +55,16 @@
 ]
 
 
+_PRIVATE_REPO_CI_OPTIONAL_PATTERNS = {
+    "    permissions:\n      contents: write\n",
+    "          python -m frequenz.repo.config.cli.version.mike.info\n",
+    "        run: |\n"
+    '          mike deploy --update-aliases --title "$TITLE" "$VERSION" '
+    "$ALIASES\n",
+    "          python -m frequenz.repo.config.cli.version.mike.sort versions.json\n",
+}
+
+
 def main() -> None:
     """Run the migration steps."""
     # Add a separation line like this one after each migration step.
@@ -92,6 +102,8 @@ def main() -> None:
 
 def migrate_ci_workflows() -> None:
     """Update the generated CI workflows to the latest template."""
+    is_private_repo = has_private_repo_indicators()
+
     _migrate_workflow_file(
         Path(".github/workflows/ci-pr.yaml"),
         [
@@ -120,8 +132,15 @@ def migrate_ci_workflows() -> None:
         description="updated CI pull-request workflow",
     )
 
+    ci_workflow = Path(".github/workflows/ci.yaml")
+    private_ci_publish_jobs: list[str] = []
+    if is_private_repo and ci_workflow.exists():
+        private_ci_publish_jobs = find_ci_publish_jobs(
+            _normalize_content(ci_workflow.read_text(encoding="utf-8"))
+        )
+
     _migrate_workflow_file(
-        Path(".github/workflows/ci.yaml"),
+        ci_workflow,
         [
             (
                 "  workflow_dispatch:\n\nenv:\n",
@@ -247,8 +266,19 @@ def migrate_ci_workflows() -> None:
             ),
         ],
         description="updated main CI workflow",
+        ignore_missing_patterns=(
+            _PRIVATE_REPO_CI_OPTIONAL_PATTERNS if is_private_repo else None
+        ),
     )
 
+    if is_private_repo and private_ci_publish_jobs:
+        jobs = ", ".join(f"`{job}`" for job in private_ci_publish_jobs)
+        manual_step(
+            f"{ci_workflow} still contains {jobs}. This repository appears to be "
+            "private, so those publish jobs usually should be removed manually "
+            "after the migration, even though the workflow was updated."
+        )
+
 
 def migrate_dependabot_workflows() -> None:
     """Update the generated Dependabot automation workflows."""
@@ -444,6 +474,7 @@ def _migrate_workflow_file(
     replacements: list[tuple[str, str]],
     *,
     description: str,
+    ignore_missing_patterns: set[str] | None = None,
 ) -> None:
     """Apply text replacements to a generated workflow file.
 
@@ -463,6 +494,12 @@ def _migrate_workflow_file(
 
     updated = _pin_workflow_action_references(content)
     updated, missing_patterns = _apply_idempotent_replacements(updated, replacements)
+    if ignore_missing_patterns:
+        missing_patterns = [
+            pattern
+            for pattern in missing_patterns
+            if pattern not in ignore_missing_patterns
+        ]
 
     if updated == content:
         if not missing_patterns:
@@ -734,6 +771,49 @@ def read_cookiecutter_str_var(name: str) -> str | None:
     return value
 
 
+def has_private_repo_indicators() -> bool:
+    """Return whether the repository appears to be private."""
+    github_org = read_cookiecutter_str_var("github_org")
+    if github_org is not None and github_org != "frequenz-floss":
+        return True
+
+    license_name = read_cookiecutter_str_var("license")
+    if license_name == "Proprietary":
+        return True
+
+    pyproject_path = Path("pyproject.toml")
+    if pyproject_path.exists():
+        pyproject = _normalize_content(pyproject_path.read_text(encoding="utf-8"))
+        if 'license = "LicenseRef-Proprietary"' in pyproject:
+            return True
+
+    try:
+        stdout = subprocess.check_output(
+            ["gh", "repo", "view", "--json", "owner"],
+            text=True,
+            stderr=subprocess.PIPE,
+        )
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        return False
+
+    try:
+        info: dict[str, Any] = json.loads(stdout)
+        owner = info["owner"]["login"]
+    except (KeyError, TypeError, json.JSONDecodeError):
+        return False
+
+    return owner != "frequenz-floss"
+
+
+def find_ci_publish_jobs(content: str) -> list[str]:
+    """Return CI publish job names found in the workflow content."""
+    jobs: list[str] = []
+    for job_name in ("publish-docs", "publish-to-pypi"):
+        if f"\n  {job_name}:\n" in f"\n{content}":
+            jobs.append(job_name)
+    return jobs
+
+
 def manual_step(message: str) -> None:
     """Print a manual step message in yellow."""
     _manual_steps.append(message)
diff --git a/tests/test_migrate.py b/tests/test_migrate.py
@@ -0,0 +1,186 @@
+# License: MIT
+# Copyright © 2026 Frequenz Energy-as-a-Service GmbH
+
+"""Tests for the cookiecutter migration script."""
+
+import importlib.util
+import json
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_migrate_module() -> ModuleType:
+    """Load the migration script as a module."""
+    module_path = Path(__file__).resolve().parents[1] / "cookiecutter" / "migrate.py"
+    spec = importlib.util.spec_from_file_location("cookiecutter_migrate", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_migrate_workflow_file_adds_missing_release_notes_permissions(
+    tmp_path: Path,
+) -> None:
+    """Add the release notes permissions block when it is missing."""
+    migrate = _load_migrate_module()
+    workflow = tmp_path / "release-notes-check.yml"
+    workflow.write_text(
+        """name: Release Notes Check
+
+on:
+  merge_group:
+  pull_request:
+    types:
+      - \"opened\"
+
+jobs:
+  check-release-notes:
+    name: Check release notes are updated
+    runs-on: ubuntu-slim
+    steps:
+      - name: Check for a release notes update
+        if: github.event_name == 'pull_request'
+        uses: brettcannon/check-for-changed-files@871d7b8b5917a4f6f06662e2262e8ffc51dff6d1 # v1.2.1
+        with:
+          file-pattern: \"RELEASE_NOTES.md\"
+          prereq-pattern: \"{proto,py}/**\"
+          skip-label: \"cmd:skip-release-notes\"
+""",
+        encoding="utf-8",
+    )
+
+    migrate._migrate_workflow_file(  # pylint: disable=protected-access
+        workflow,
+        migrate._RELEASE_NOTES_CHECK_REPLACEMENTS,  # pylint: disable=protected-access
+        description="updated release notes check workflow",
+    )
+
+    assert workflow.read_text(encoding="utf-8") == (
+        "name: Release Notes Check\n\n"
+        "on:\n"
+        "  merge_group:\n"
+        "  pull_request:\n"
+        "    types:\n"
+        '      - "opened"\n\n'
+        "jobs:\n"
+        "  check-release-notes:\n"
+        "    name: Check release notes are updated\n"
+        "    runs-on: ubuntu-slim\n"
+        "    permissions:\n"
+        "      # Read pull request metadata to evaluate labels and changed files.\n"
+        "      pull-requests: read\n"
+        "    steps:\n"
+        "      - name: Check for a release notes update\n"
+        "        if: github.event_name == 'pull_request'\n"
+        "        uses: brettcannon/check-for-changed-files@871d7b8b5917a4f6f06662e2262e8ffc51dff6d1 # v1.2.1\n"
+        "        with:\n"
+        '          file-pattern: "RELEASE_NOTES.md"\n'
+        '          prereq-pattern: "{proto,py}/**"\n'
+        '          skip-label: "cmd:skip-release-notes"\n'
+    )
+    assert migrate._manual_steps == []  # pylint: disable=protected-access
+
+
+def test_migrate_workflow_file_reports_missing_patterns(tmp_path: Path) -> None:
+    """Report the full missing patterns when a workflow cannot be migrated."""
+    migrate = _load_migrate_module()
+    workflow = tmp_path / "release-notes-check.yml"
+    workflow.write_text(
+        """name: Release Notes Check
+
+jobs:
+  check-release-notes:
+    name: Check release notes are updated
+""",
+        encoding="utf-8",
+    )
+
+    migrate._migrate_workflow_file(  # pylint: disable=protected-access
+        workflow,
+        migrate._RELEASE_NOTES_CHECK_REPLACEMENTS,  # pylint: disable=protected-access
+        description="updated release notes check workflow",
+    )
+
+    assert len(migrate._manual_steps) == 1  # pylint: disable=protected-access
+    assert (
+        f"Could not find the expected pattern(s) in {workflow}."
+        in migrate._manual_steps[0]  # pylint: disable=protected-access
+    )
+    assert "Pattern 1:" in migrate._manual_steps[0]  # pylint: disable=protected-access
+    assert "Pattern 2:" in migrate._manual_steps[0]  # pylint: disable=protected-access
+    assert "permissions:" in migrate._manual_steps[0]  # pylint: disable=protected-access
+    assert "runs-on: ubuntu-slim" in migrate._manual_steps[0]  # pylint: disable=protected-access
+
+
+def test_migrate_workflow_file_ignores_private_ci_publish_patterns(
+    tmp_path: Path,
+) -> None:
+    """Ignore private-repo CI publish patterns when they are absent."""
+    migrate = _load_migrate_module()
+    workflow = tmp_path / "ci.yaml"
+    workflow.write_text("name: CI\n", encoding="utf-8")
+
+    replacements = [
+        (pattern, f"replacement {index}\n")
+        for index, pattern in enumerate(
+            migrate._PRIVATE_REPO_CI_OPTIONAL_PATTERNS,  # pylint: disable=protected-access
+            start=1,
+        )
+    ]
+
+    migrate._migrate_workflow_file(  # pylint: disable=protected-access
+        workflow,
+        replacements,
+        description="updated main CI workflow",
+        ignore_missing_patterns=migrate._PRIVATE_REPO_CI_OPTIONAL_PATTERNS,  # pylint: disable=protected-access
+    )
+
+    assert workflow.read_text(encoding="utf-8") == "name: CI\n"
+    assert migrate._manual_steps == []  # pylint: disable=protected-access
+
+
+def test_migrate_ci_workflows_warns_about_private_publish_jobs(
+    tmp_path: Path,
+    monkeypatch,
+) -> None:
+    """Warn when a private repository still has CI publish jobs."""
+    migrate = _load_migrate_module()
+    template_root = Path(__file__).resolve().parents[1] / "cookiecutter"
+    workflow_dir = tmp_path / ".github" / "workflows"
+    workflow_dir.mkdir(parents=True)
+    workflow_dir.joinpath("ci-pr.yaml").write_text(
+        (
+            template_root
+            / "{{cookiecutter.github_repo_name}}"
+            / ".github"
+            / "workflows"
+            / "ci-pr.yaml"
+        ).read_text(encoding="utf-8"),
+        encoding="utf-8",
+    )
+    workflow_dir.joinpath("ci.yaml").write_text(
+        (
+            template_root
+            / "{{cookiecutter.github_repo_name}}"
+            / ".github"
+            / "workflows"
+            / "ci.yaml"
+        ).read_text(encoding="utf-8"),
+        encoding="utf-8",
+    )
+    (tmp_path / ".cookiecutter-replay.json").write_text(
+        json.dumps({"cookiecutter": {"github_org": "private-org", "license": "MIT"}}),
+        encoding="utf-8",
+    )
+
+    monkeypatch.chdir(tmp_path)
+    migrate.migrate_ci_workflows()
+
+    assert len(migrate._manual_steps) == 1  # pylint: disable=protected-access
+    assert (
+        "still contains `publish-docs`, `publish-to-pypi`" in migrate._manual_steps[0]
+    )  # pylint: disable=protected-access
+    assert "appears to be private" in migrate._manual_steps[0]  # pylint: disable=protected-access
