Merge branch 'main' into chore/auto-copilot-collections

Author: cbartz

charmcraft.yaml

@@ -25,6 +25,8 @@ links:
 provides:
   cos-agent:
     interface: cos_agent
+  planner:
+    interface: github_runner_planner_v0
 
 requires:
   debug-ssh:

docs/changelog.md

@@ -2,6 +2,10 @@
 
 This changelog documents user-relevant changes to the GitHub runner charm.
 
+## 2026-02-12
+
+- Add support to integrate with GitHub Runner planner charm with the `github_runner_planner_v0` interface.
+
 ## 2026-02-11
 
 - Fixed charm hook errors caused by `ghapi`'s `pages()` leaving a stuck multiprocessing process that held the HTTP port.

github-runner-manager/pyproject.toml

@@ -3,7 +3,7 @@
 
 [project]
 name = "github-runner-manager"
-version = "0.11.1"
+version = "0.12.0"
 authors = [
     { name = "Canonical IS DevOps", email = "is-devops-team@canonical.com" },
 ]

src/charm.py

@@ -52,10 +52,12 @@
     LABELS_CONFIG_NAME,
     MONGO_DB_INTEGRATION_NAME,
     PATH_CONFIG_NAME,
+    PLANNER_INTEGRATION_NAME,
     TOKEN_CONFIG_NAME,
     CharmConfigInvalidError,
     CharmState,
     OpenstackImage,
+    PlannerRelationData,
     build_proxy_config_from_charm,
 )
 from errors import (
@@ -234,6 +236,13 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
             self.on[IMAGE_INTEGRATION_NAME].relation_changed,
             self._on_image_relation_changed,
         )
+        self.framework.observe(
+            self.on[PLANNER_INTEGRATION_NAME].relation_changed,
+            self._on_planner_relation_changed,
+        )
+        self.framework.observe(
+            self.on[PLANNER_INTEGRATION_NAME].relation_broken, self._on_planner_relation_broken
+        )
         self.framework.observe(self.on.check_runners_action, self._on_check_runners_action)
         self.framework.observe(self.on.flush_runners_action, self._on_flush_runners_action)
         self.framework.observe(self.on.update_status, self._on_update_status)
@@ -506,6 +515,30 @@ def _on_image_relation_changed(self, _: ops.RelationChangedEvent) -> None:
         self._manager_client.flush_runner()
         self.unit.status = ActiveStatus()
 
+    @catch_charm_errors
+    def _on_planner_relation_changed(self, _: ops.RelationChangedEvent) -> None:
+        """Handle planner relation changed event."""
+        self.unit.status = MaintenanceStatus("Setup planner")
+        state = self._setup_state()
+        self._setup_service(state)
+        if self.unit.is_leader():
+            flavor_data = PlannerRelationData(
+                flavor=self.app.name,
+                labels=state.charm_config.labels,
+                minimum_pressure=state.runner_config.base_virtual_machines,
+            )
+            for relation in self.model.relations[PLANNER_INTEGRATION_NAME]:
+                relation.data[self.app].update(flavor_data.to_relation_data())
+        self.unit.status = ActiveStatus()
+
+    @catch_charm_errors
+    def _on_planner_relation_broken(self, _: ops.RelationBrokenEvent) -> None:
+        """Handle planner relation broken event."""
+        self.unit.status = MaintenanceStatus("Cleanup planner data")
+        state = self._setup_state()
+        self._setup_service(state)
+        self.unit.status = ActiveStatus()
+
     @catch_charm_errors
     def _on_database_created(self, _: ops.RelationEvent) -> None:
         """Handle the MongoDB database created event."""

src/charm_state.py

@@ -9,15 +9,21 @@
 import logging
 import re
 from pathlib import Path
-from typing import Literal, cast
+from typing import Final, Literal, cast
 from urllib.parse import urlsplit
 
 import yaml
 from charms.data_platform_libs.v0.data_interfaces import DatabaseRequires
 from github_runner_manager.configuration import ProxyConfig, SSHDebugConnection
 from github_runner_manager.configuration.github import GitHubPath, parse_github_path
 from ops import CharmBase
-from pydantic import BaseModel, MongoDsn, ValidationError, create_model_from_typeddict, validator
+from pydantic import (
+    BaseModel,
+    MongoDsn,
+    ValidationError,
+    create_model_from_typeddict,
+    validator,
+)
 
 from errors import MissingMongoDBError
 from models import AnyHttpsUrl, FlavorLabel, OpenStackCloudsYAML
@@ -61,10 +67,53 @@
 DEBUG_SSH_INTEGRATION_NAME = "debug-ssh"
 IMAGE_INTEGRATION_NAME = "image"
 MONGO_DB_INTEGRATION_NAME = "mongodb"
+PLANNER_INTEGRATION_NAME = "planner"
+
+# Keys and defaults for planner relation app data bag
+PLANNER_FLAVOR_RELATION_KEY: Final[str] = "flavor"
+PLANNER_LABELS_RELATION_KEY: Final[str] = "labels"
+PLANNER_PLATFORM_RELATION_KEY: Final[str] = "platform"
+PLANNER_PRIORITY_RELATION_KEY: Final[str] = "priority"
+PLANNER_MINIMUM_PRESSURE_RELATION_KEY: Final[str] = "minimum-pressure"
+PLANNER_DEFAULT_PLATFORM: Final[str] = "github"
+PLANNER_DEFAULT_PRIORITY: Final[int] = 50
 
 LogLevel = Literal["CRITICAL", "FATAL", "ERROR", "WARNING", "INFO", "DEBUG"]
 
 
+@dataclasses.dataclass(frozen=True)
+class PlannerRelationData:
+    """Data written to the planner relation app databag.
+
+    Attributes:
+        flavor: The flavor name (app name).
+        labels: Runner labels for this flavor.
+        platform: The platform identifier.
+        priority: Scheduling priority.
+        minimum_pressure: Minimum number of runners to maintain.
+    """
+
+    flavor: str
+    labels: tuple[str, ...]
+    platform: str = PLANNER_DEFAULT_PLATFORM
+    priority: int = PLANNER_DEFAULT_PRIORITY
+    minimum_pressure: int = 0
+
+    def to_relation_data(self) -> dict[str, str]:
+        """Serialize to relation databag format.
+
+        Returns:
+            Dictionary of string key-value pairs for the Juju relation databag.
+        """
+        return {
+            PLANNER_FLAVOR_RELATION_KEY: self.flavor,
+            PLANNER_LABELS_RELATION_KEY: json.dumps(list(self.labels)),
+            PLANNER_PLATFORM_RELATION_KEY: self.platform,
+            PLANNER_PRIORITY_RELATION_KEY: str(self.priority),
+            PLANNER_MINIMUM_PRESSURE_RELATION_KEY: str(self.minimum_pressure),
+        }
+
+
 @dataclasses.dataclass
 class GithubConfig:
     """Charm configuration related to GitHub.
@@ -455,7 +504,6 @@ def from_charm(cls, charm: CharmBase) -> "CharmConfig":
         runner_manager_log_level = cast(
             LogLevel, charm.config.get(RUNNER_MANAGER_LOG_LEVEL_CONFIG_NAME, "INFO")
         )
-        # pydantic allows to pass str as AnyHttpUrl, mypy complains about it
         return cls(
             allow_external_contributor=cast(
                 bool, charm.config.get(ALLOW_EXTERNAL_CONTRIBUTOR_CONFIG_NAME, False)

tests/integration/conftest.py

@@ -959,3 +959,51 @@ def show_debug_log(juju: jubilant.Juju):
         yield juju
         show_debug_log(juju)
         return
+
+
+@pytest.fixture(scope="module")
+def planner_token_secret_name() -> str:
+    """Planner token secret name."""
+    return "planner-token-secret"
+
+
+@pytest_asyncio.fixture(scope="module")
+async def planner_token_secret(model: Model, planner_token_secret_name: str) -> str:
+    """Create a planner token secret."""
+    return await model.add_secret(
+        name=planner_token_secret_name, data_args=["token=MOCK_PLANNER_TOKEN"]
+    )
+
+
+@pytest_asyncio.fixture(scope="module")
+async def mock_planner_app(model: Model, planner_token_secret) -> AsyncIterator[Application]:
+    """Deploy a minimal any-charm that acts as the requires side of the planner relation."""
+    planner_name = "planner"
+
+    any_charm_src_overwrite = {
+        "any_charm.py": textwrap.dedent(f"""\
+            from any_charm_base import AnyCharmBase
+
+            class AnyCharm(AnyCharmBase):
+                def __init__(self, *args, **kwargs):
+                    super().__init__(*args, **kwargs)
+                    self.framework.observe(
+                        self.on["require-github-runner-planner-v0"].relation_changed,
+                        self._on_planner_relation_changed,
+                    )
+
+                def _on_planner_relation_changed(self, event):
+                    event.relation.data[self.unit]["endpoint"] = "http://mock:8080"
+                    event.relation.data[self.unit]["token"] = "{planner_token_secret}"
+            """),
+    }
+
+    planner_app: Application = await model.deploy(
+        "any-charm",
+        planner_name,
+        channel="latest/beta",
+        config={"src-overwrite": json.dumps(any_charm_src_overwrite)},
+    )
+
+    await model.wait_for_idle(apps=[planner_app.name], status=ACTIVE, timeout=10 * 60)
+    yield planner_app

tests/integration/test_charm_no_runner.py

@@ -3,14 +3,18 @@
 
 """Integration tests for github-runner charm with no runner."""
 
+import json
 import logging
 
+import jubilant
 import pytest
 from github_runner_manager.reconcile_service import (
     RECONCILE_SERVICE_START_MSG,
     RECONCILE_START_MSG,
 )
 from juju.application import Application
+from juju.model import Model
+from ops import ActiveStatus
 
 from charm_state import BASE_VIRTUAL_MACHINES_CONFIG_NAME
 from manager_service import GITHUB_RUNNER_MANAGER_SERVICE_NAME
@@ -109,7 +113,8 @@ async def test_manager_service_started(
     # 1.
     await run_in_unit(
         unit,
-        f"sudo systemctl status {GITHUB_RUNNER_MANAGER_SERVICE_NAME}@{unit.name.replace('/', '-')}.service",
+        f"sudo systemctl status {GITHUB_RUNNER_MANAGER_SERVICE_NAME}"
+        f"@{unit.name.replace('/', '-')}.service",
         timeout=60,
         assert_on_failure=True,
         assert_msg="GitHub runner manager service not healthy",
@@ -134,3 +139,57 @@ async def test_manager_service_started(
     log = await get_github_runner_manager_service_log(unit)
     assert RECONCILE_SERVICE_START_MSG not in log
     assert RECONCILE_START_MSG in log
+
+
+@pytest.mark.asyncio
+@pytest.mark.abort_on_fail
+async def test_planner_integration(
+    model: Model,
+    juju: jubilant.Juju,
+    app_no_runner: Application,
+    mock_planner_app: Application,
+    planner_token_secret_name: str,
+) -> None:
+    """
+    arrange: A working application with no runners and a mock planner, and the secret granted.
+    act:
+        1. Integrate the application with the mock planner.
+        2. Remove the integration.
+    assert:
+        1. The charm writes its flavor data to the planner relation app data bag.
+        2. The charm returns to active status after the relation is removed.
+    """
+    await model.grant_secret(planner_token_secret_name, app_no_runner.name)
+    await model.grant_secret(planner_token_secret_name, mock_planner_app.name)
+
+    await model.relate(f"{app_no_runner.name}:planner", mock_planner_app.name)
+    await model.wait_for_idle(
+        apps=[app_no_runner.name, mock_planner_app.name],
+        status=ActiveStatus.name,
+        idle_period=30,
+        timeout=10 * 60,
+    )
+
+    # Verify the runner charm wrote flavor data to the relation app databag.
+    # Query from the planner unit's perspective so "application-data" shows the
+    # remote (runner) app's data rather than the planner's own app data.
+    planner_unit_name = mock_planner_app.units[0].name
+    raw = juju.cli("show-unit", planner_unit_name, "--format", "json")
+    unit_data = json.loads(raw)[planner_unit_name]
+    planner_rel = next(
+        rel
+        for rel in unit_data["relation-info"]
+        if rel["endpoint"] == "require-github-runner-planner-v0"
+    )
+    app_data = planner_rel["application-data"]
+    assert app_data["flavor"] == app_no_runner.name
+    assert app_data["platform"] == "github"
+    assert app_data["priority"] == "50"
+    assert app_data["minimum-pressure"] == "0"
+
+    await mock_planner_app.remove_relation(
+        "require-github-runner-planner-v0", f"{app_no_runner.name}:planner"
+    )
+    await model.wait_for_idle(
+        apps=[app_no_runner.name], status=ActiveStatus.name, idle_period=30, timeout=10 * 60
+    )

tests/unit/conftest.py

@@ -160,6 +160,7 @@ def complete_charm_state_fixture():
             manager_proxy_command="ssh -W %h:%p example.com",
             use_aproxy=True,
             runner_manager_log_level="INFO",
+            planner=None,
         ),
         runner_config=charm_state.OpenstackRunnerConfig(
             base_virtual_machines=1,

tests/unit/factories.py

@@ -32,6 +32,7 @@
     OPENSTACK_FLAVOR_CONFIG_NAME,
     OPENSTACK_NETWORK_CONFIG_NAME,
     PATH_CONFIG_NAME,
+    PLANNER_INTEGRATION_NAME,
     RECONCILE_INTERVAL_CONFIG_NAME,
     RUNNER_MANAGER_LOG_LEVEL_CONFIG_NAME,
     TEST_MODE_CONFIG_NAME,
@@ -111,6 +112,7 @@ class Meta:
             COS_AGENT_INTEGRATION_NAME: [],
             DEBUG_SSH_INTEGRATION_NAME: [],
             MONGO_DB_INTEGRATION_NAME: [],
+            PLANNER_INTEGRATION_NAME: [],
         }
     )
 

tests/unit/test_charm.py

@@ -34,6 +34,14 @@
     OPENSTACK_CLOUDS_YAML_CONFIG_NAME,
     OPENSTACK_FLAVOR_CONFIG_NAME,
     PATH_CONFIG_NAME,
+    PLANNER_DEFAULT_PLATFORM,
+    PLANNER_DEFAULT_PRIORITY,
+    PLANNER_FLAVOR_RELATION_KEY,
+    PLANNER_INTEGRATION_NAME,
+    PLANNER_LABELS_RELATION_KEY,
+    PLANNER_MINIMUM_PRESSURE_RELATION_KEY,
+    PLANNER_PLATFORM_RELATION_KEY,
+    PLANNER_PRIORITY_RELATION_KEY,
     TOKEN_CONFIG_NAME,
     USE_APROXY_CONFIG_NAME,
     OpenStackCloudsYAML,
@@ -703,3 +711,32 @@ def test_database_integration_events_setup_service(
     else:
         getattr(harness.charm.database.on, hook).emit(relation=relation_mock)
     setup_service_mock.assert_called_once()
+
+
+def test_planner_relation_changed_writes_flavor(monkeypatch: pytest.MonkeyPatch):
+    """
+    arrange: Set up charm with mocked _setup_state and _setup_service.
+    act: Fire planner relation_changed event.
+    assert: The app data bag contains all flavor fields for the planner.
+    """
+    harness = Harness(GithubRunnerCharm)
+    harness.set_leader(True)
+    relation_id = harness.add_relation(PLANNER_INTEGRATION_NAME, "planner-app")
+    harness.add_relation_unit(relation_id, "planner-app/0")
+    harness.begin()
+    monkeypatch.setattr("charm.manager_service", MagicMock())
+    state_mock = MagicMock()
+    state_mock.charm_config.labels = ("label1", "label2")
+    state_mock.runner_config.base_virtual_machines = 3
+    harness.charm._setup_state = MagicMock(return_value=state_mock)
+    harness.charm._setup_service = MagicMock()
+
+    harness.update_relation_data(relation_id, "planner-app/0", {"endpoint": "http://example.com"})
+
+    assert harness.get_relation_data(relation_id, harness.charm.app) == {
+        PLANNER_FLAVOR_RELATION_KEY: harness.charm.app.name,
+        PLANNER_LABELS_RELATION_KEY: '["label1", "label2"]',
+        PLANNER_PLATFORM_RELATION_KEY: PLANNER_DEFAULT_PLATFORM,
+        PLANNER_PRIORITY_RELATION_KEY: str(PLANNER_DEFAULT_PRIORITY),
+        PLANNER_MINIMUM_PRESSURE_RELATION_KEY: "3",
+    }