docs: ssh debug integration docs

.github/workflows/integration_test.yaml

@@ -4,6 +4,8 @@ on:
   pull_request:
 
 jobs:
+  # test option values defined at test/conftest.py are passed on via repository secret
+  # INTEGRATION_TEST_ARGS to operator-workflows automatically.
   integration-tests-juju2:
     name: Integration test with juju 2.9
     uses: canonical/operator-workflows/.github/workflows/integration_test.yaml@main

docs/explanation/ssh-debug.md

@@ -0,0 +1,12 @@
+# SSH Debug
+
+SSH debugging allows a user to identify and resolve issues or errors that occur through the secure
+shell (SSH) connection between a client and a server.
+
+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,53 @@
+# 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.
+
+## 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@main
+```
+
+The output of the action looks like the following.
+
+```
+<workflow setup logs redacted>
+SSH: ssh -p 10022 <user>@<ip>
+or: ssh -i <path-to-private-SSH-key> -p10022 <user>@<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`

tests/conftest.py

@@ -9,11 +9,18 @@
 
 def pytest_addoption(parser: Parser):
     """Add options to pytest parser."""
+    # The path to repository in <org>/<repo> or <user>/<repo> format.
     parser.addoption("--path", action="store")
+    # The GitHub Personal Access Token.
     parser.addoption("--token", action="store")
+    # The prebuilt github-runner-operator charm file.
     parser.addoption("--charm-file", action="store")
+    # An alternative token to test repo-policy-compliance.
     parser.addoption("--token-alt", action="store")
+    # HTTP proxy configuration value for juju model proxy configuration.
     parser.addoption("--http-proxy", action="store")
+    # HTTPS proxy configuration value for juju model proxy configuration.
     parser.addoption("--https-proxy", action="store")
+    # No proxy configuration value for juju model proxy configuration.
     parser.addoption("--no-proxy", action="store")
     parser.addoption("--loop-device", action="store")

tests/integration/conftest.py

@@ -86,23 +86,32 @@ def charm_file(pytestconfig: pytest.Config, loop_device: Optional[str]) -> str:
 def path(pytestconfig: pytest.Config) -> str:
     """Configured path setting."""
     path = pytestconfig.getoption("--path")
-    assert path, "Please specify the --path command line option"
+    assert path, (
+        "Please specify the --path command line option with repository "
+        "path of <org>/<repo> or <user>/<repo> format."
+    )
     return path
 
 
 @pytest.fixture(scope="module")
 def token(pytestconfig: pytest.Config) -> str:
     """Configured token setting."""
     token = pytestconfig.getoption("--token")
-    assert token, "Please specify the --token command line option"
+    assert token, (
+        "Please specify the --token command line option with GitHub Personal Access "
+        "Token value."
+    )
     return token
 
 
 @pytest.fixture(scope="module")
 def token_alt(pytestconfig: pytest.Config, token: str) -> str:
     """Configured token_alt setting."""
     token_alt = pytestconfig.getoption("--token-alt")
-    assert token_alt, "Please specify the --token-alt command line option"
+    assert token_alt, (
+        "Please specify the --token-alt command line option with GitHub Personal "
+        "Access Token value."
+    )
     assert token_alt != token, "Please specify a different token for --token-alt"
     return token_alt