docs: ssh debug integration docs

.github/workflows/integration_test.yaml

@@ -13,7 +13,7 @@ jobs:
       pre-run-script: scripts/pre-integration-test.sh
       provider: lxd
       test-tox-env: integration-juju2.9
-      modules: '["test_charm_fork_repo", "test_charm_no_runner", "test_charm_scheduled_events", "test_charm_one_runner", "test_charm_metrics", "test_self_hosted_runner", "test_charm_with_proxy", "test_charm_with_juju_storage"]'
+      modules: '["test_charm_fork_repo", "test_charm_no_runner", "test_charm_scheduled_events", "test_charm_one_runner", "test_charm_metrics", "test_self_hosted_runner", "test_charm_with_proxy", "test_charm_with_juju_storage", "test_debug_ssh"]'
   integration-tests-juju3:
     name: Integration test with juju 3.1
     uses: canonical/operator-workflows/.github/workflows/integration_test.yaml@main
@@ -23,4 +23,4 @@ jobs:
       pre-run-script: scripts/pre-integration-test.sh
       provider: lxd
       test-tox-env: integration-juju3.1
-      modules: '["test_charm_fork_repo", "test_charm_no_runner", "test_charm_scheduled_events", "test_charm_one_runner", "test_charm_metrics", "test_self_hosted_runner", "test_charm_with_proxy", "test_charm_with_juju_storage"]'
+      modules: '["test_charm_fork_repo", "test_charm_no_runner", "test_charm_scheduled_events", "test_charm_one_runner", "test_charm_metrics", "test_self_hosted_runner", "test_charm_with_proxy", "test_charm_with_juju_storage", "test_debug_ssh"]'

.github/workflows/workflow_dispatch_ssh_debug.yaml

@@ -0,0 +1,17 @@
+name: Workflow Dispatch Tests (ssh-debug/tmate)
+
+on:
+  # Manually dispatched workflow action
+  workflow_dispatch:
+    inputs:
+      runner:
+        description: 'Self hosted gh runner'
+        required: true
+
+jobs:
+  workflow-dispatch-tests:
+    runs-on: [self-hosted, linux, x64, "${{ inputs.runner }}"]
+    steps:
+    - name: Setup tmate session
+      uses: canonical/action-tmate@chore/env_var_change
+      timeout-minutes: 1

docs/explanation/ssh-debug.md

@@ -0,0 +1,9 @@
+# SSH Debug
+
+To enhance the security of the runner and the infrastructure behind the runner, only user ssh-keys
+registered on [Authorized Keys](https://github.com/tmate-io/tmate-ssh-server/pull/93) are allowed
+by default on [tmate-ssh-server charm](https://charmhub.io/tmate-ssh-server/).
+
+Authorized keys are registered via [action-tmate](https://github.com/canonical/action-tmate/)'s
+`limit-access-to-actor` feature. This feature uses GitHub users's SSH key to launch an instance
+of tmate session with `-a` option, which adds the user's SSH key to `~/.ssh/authorized_keys`.

docs/how-to/debug-with-ssh.md

@@ -0,0 +1,56 @@
+# How to debug with ssh
+
+The charm exposes an integration `debug-ssh` interface which can be used with
+[tmate-ssh-server charm](https://charmhub.io/tmate-ssh-server/) to pre-configure runners with
+environment variables to be picked up by [action-tmate](https://github.com/canonical/action-tmate/)
+for automatic configuration.
+
+## Prerequisites
+
+To enhance the security of self-hosted runners and its infrastracture, only authorized connections
+can be established. Hence, action-tmate users must have
+[ssh-key registered](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account)
+on the GitHub account.
+
+For users using Canonical's self-hosted runners, access to tmate-ssh-server is provided only within
+Canonical VPN. 
+
+## Deploying
+
+Use the following command to deploy and integrate github-runner with tmate-ssh-server.
+
+```shell
+juju deploy tmate-ssh-server
+juju integrate tmate-ssh-server github-runner
+```
+
+Idle runners will be flushed and restarted. Busy runners will be configured automatically on next
+spawn.
+
+## Using the action
+
+Create a workflow that looks like the following within your workflow to enable action-tmate.
+
+```yaml
+name: SSH Debug workflow example
+
+on: [pull_request]
+
+jobs:
+  build:
+    runs-on: [self-hosted]
+    steps:
+    - uses: actions/checkout@v3
+    - name: Setup tmate session
+      uses: canonical/action-tmate@master
+```
+
+The output of the action looks like the following.
+
+```
+<workflow setup logs redacted>
+SSH: ssh -p 10022 <token>@<ip>
+or: ssh -i <path-to-private-SSH-key> -p10022 <token>@<ip>
+```
+
+Read more about [action-tmate's usage here](https://github.com/canonical/action-tmate).

docs/reference/integrations.md

@@ -0,0 +1,11 @@
+# Integrations
+
+### debug-ssh
+
+_Interface_: debug-ssh
+_Supported charms_: [tmate-ssh-server](https://charmhub.io/tmate-ssh-server)
+
+Debug-ssh integration provides necessary information for runners to provide ssh reverse-proxy
+applications to setup inside the runner. 
+
+Example debug-ssh integrate command: `juju integrate github-runner tmate-ssh-server`

src/charm_state.py

@@ -309,6 +309,9 @@ def from_charm(cls, charm: CharmBase) -> "State":
         # Convert pydantic object to python object serializable by json module.
         state_dict["proxy_config"] = json.loads(state_dict["proxy_config"].json())
         state_dict["charm_config"] = json.loads(state_dict["charm_config"].json())
+        state_dict["ssh_debug_info"] = (
+            json.loads(state_dict["ssh_debug_info"].json()) if ssh_debug_info else None
+        )
         json_data = json.dumps(state_dict, ensure_ascii=False)
         CHARM_STATE_PATH.write_text(json_data, encoding="utf-8")
 

tests/integration/conftest.py

@@ -12,17 +12,20 @@
 import pytest
 import pytest_asyncio
 import yaml
+from git import Repo
 from github import Github, GithubException
 from github.Branch import Branch
 from github.Repository import Repository
 from juju.application import Application
+from juju.client._definitions import FullStatus, UnitStatus
 from juju.model import Model
 from pytest_operator.plugin import OpsTest
 
 from tests.integration.helpers import (
     deploy_github_runner_charm,
     ensure_charm_has_runner,
     reconcile,
+    wait_for,
 )
 
 
@@ -245,6 +248,35 @@ async def app_runner(
     return application
 
 
+@pytest_asyncio.fixture(scope="module", name="tmate_ssh_server_app")
+async def tmate_ssh_server_app_fixture(
+    model: Model, app: Application
+) -> AsyncIterator[Application]:
+    """tmate-ssh-server charm application related to GitHub-Runner app charm."""
+    tmate_app: Application = await model.deploy("tmate-ssh-server", channel="edge")
+    await app.relate("debug-ssh", f"{tmate_app.name}:debug-ssh")
+    await model.wait_for_idle(raise_on_error=False, timeout=60 * 30)
+
+    return tmate_app
+
+
+@pytest_asyncio.fixture(scope="module", name="tmate_ssh_server_unit_ip")
+async def tmate_ssh_server_unit_ip_fixture(
+    model: Model,
+    tmate_ssh_server_app: Application,
+) -> AsyncIterator[str]:
+    """tmate-ssh-server charm unit ip."""
+    status: FullStatus = await model.get_status([tmate_ssh_server_app.name])
+    try:
+        unit_status: UnitStatus = next(
+            iter(status.applications[tmate_ssh_server_app.name].units.values())
+        )
+        assert unit_status.public_address, "Invalid unit address"
+        return unit_status.public_address
+    except StopIteration as exc:
+        raise StopIteration("Invalid unit status") from exc
+
+
 @pytest.fixture(scope="module")
 def github_client(token: str) -> Github:
     """Returns the github client."""
@@ -354,3 +386,28 @@ async def app_juju_storage(
         reconcile_interval=60,
     )
     return application
+
+
+@pytest_asyncio.fixture(scope="module", name="test_github_branch")
+async def test_github_branch_fixture(github_repository: Repository) -> AsyncIterator[Branch]:
+    """Create a new branch for testing, from latest commit in current branch."""
+    test_branch = f"test-{secrets.token_hex(4)}"
+    branch_ref = github_repository.create_git_ref(
+        ref=f"refs/heads/{test_branch}", sha=Repo().head.commit.hexsha
+    )
+
+    def get_branch():
+        """Get newly created branch."""
+        try:
+            branch = github_repository.get_branch(test_branch)
+        except GithubException as err:
+            if err.status == 404:
+                return False
+            raise
+        return branch
+
+    await wait_for(get_branch)
+
+    yield get_branch()
+
+    branch_ref.delete()

tests/integration/helpers.py

@@ -3,10 +3,12 @@
 
 """Utilities for integration test."""
 
+import inspect
 import json
 import subprocess
+import time
 from asyncio import sleep
-from typing import Any
+from typing import Any, Awaitable, Callable, Union
 
 import juju.version
 import yaml
@@ -353,3 +355,42 @@ async def deploy_github_runner_charm(
 
     await model.wait_for_idle(status=ACTIVE, timeout=60 * 30)
     return application
+
+
+async def wait_for(
+    func: Callable[[], Union[Awaitable, Any]],
+    timeout: int = 300,
+    check_interval: int = 10,
+) -> Any:
+    """Wait for function execution to become truthy.
+
+    Args:
+        func: A callback function to wait to return a truthy value.
+        timeout: Time in seconds to wait for function result to become truthy.
+        check_interval: Time in seconds to wait between ready checks.
+
+    Raises:
+        TimeoutError: if the callback function did not return a truthy value within timeout.
+
+    Returns:
+        The result of the function if any.
+    """
+    deadline = time.time() + timeout
+    is_awaitable = inspect.iscoroutinefunction(func)
+    while time.time() < deadline:
+        if is_awaitable:
+            if result := await func():
+                return result
+        else:
+            if result := func():
+                return result
+        time.sleep(check_interval)
+
+    # final check before raising TimeoutError.
+    if is_awaitable:
+        if result := await func():
+            return result
+    else:
+        if result := func():
+            return result
+    raise TimeoutError()

tests/integration/requirements.txt

@@ -0,0 +1 @@
+GitPython>3,<4

tests/integration/test_debug_ssh.py

@@ -0,0 +1,74 @@
+# Copyright 2024 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+"""Integration tests for github-runner charm with ssh-debug integration."""
+import typing
+import zipfile
+from io import BytesIO
+
+import requests
+from github.Branch import Branch
+from github.Repository import Repository
+from github.Workflow import Workflow
+from github.WorkflowRun import WorkflowRun
+
+from tests.integration.helpers import wait_for
+
+
+async def test_ssh_debug(
+    github_repository: Repository,
+    test_github_branch: Branch,
+    app_name: str,
+    token: str,
+    tmate_ssh_server_unit_ip: str,
+):
+    """
+    arrange: given an integrated GitHub-Runner charm and tmate-ssh-server charm.
+    act: when canonical/action-tmate is triggered.
+    assert: the ssh connection info from action-log and tmate-ssh-server matches.
+    """
+    # trigger tmate action
+    workflow: Workflow = github_repository.get_workflow("workflow_dispatch_ssh_debug.yaml")
+    assert workflow.create_dispatch(
+        test_github_branch, inputs={"runner": app_name}
+    ), "Failed to dispatch workflow"
+
+    # get action logs
+    def latest_workflow_run() -> typing.Optional[WorkflowRun]:
+        """Get latest workflow run."""
+        try:
+            last_run: WorkflowRun = next(workflow.get_runs())
+        except StopIteration:
+            return None
+        if last_run.head_branch != test_github_branch:
+            return None
+        return last_run
+
+    await wait_for(latest_workflow_run)
+    lastest_run = typing.cast(WorkflowRun, latest_workflow_run())
+
+    def is_workflow_complete():
+        """Return if the workflow is complete."""
+        lastest_run.update()
+        return lastest_run.status == "completed"
+
+    await wait_for(is_workflow_complete)
+
+    response = requests.get(
+        lastest_run.logs_url,
+        headers={
+            "Accept": "application/vnd.github+json",
+            "Authorization": f"Bearer {token}",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    )
+    zip_data = BytesIO(response.content)
+    with zipfile.ZipFile(zip_data, "r") as zip_ref:
+        tmate_log_filename = next(
+            iter([name for name in zip_ref.namelist() if "Setup tmate session" in name])
+        )
+        logs = str(zip_ref.read(tmate_log_filename), encoding="utf-8")
+
+    # ensure ssh connection info printed in logs.
+    assert tmate_ssh_server_unit_ip in logs, "Tmate ssh server IP not found in action logs."
+    assert "10022" in logs, "Tmate ssh server connection port not found in action logs."

tox.ini

@@ -114,6 +114,7 @@ deps =
     # Type error problem with newer version of macaroonbakery
     macaroonbakery==1.3.2
     -r{toxinidir}/requirements.txt
+    -r{[vars]tst_path}integration/requirements.txt
 commands =
     pytest -v --tb native --ignore={[vars]tst_path}unit --log-cli-level=INFO -s {posargs}