hermes-github-app-plugin 0.1.1__tar.gz → 0.2.0__tar.gz

hermes_github_app_plugin-0.2.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10

{hermes_github_app_plugin-0.1.1 → hermes_github_app_plugin-0.2.0}/.github/workflows/cd.yaml

@@ -15,8 +15,8 @@ jobs:
     outputs:
       release_tag: ${{ steps.validate.outputs.release_tag }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.12'
       - name: Validate tag and package version
@@ -47,8 +47,8 @@ jobs:
     if: needs.validate-tag.outputs.release_tag == 'true'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.12'
           cache: pip
@@ -59,7 +59,7 @@ jobs:
       - name: Check distribution metadata
         run: python -m twine check dist/*
       - name: Upload distribution artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: python-distribution
           path: dist/*
@@ -75,7 +75,7 @@ jobs:
       id-token: write
     steps:
       - name: Download distribution artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: python-distribution
           path: dist

{hermes_github_app_plugin-0.1.1 → hermes_github_app_plugin-0.2.0}/.github/workflows/ci.yaml

@@ -14,8 +14,8 @@ jobs:
       matrix:
         python-version: ["3.10", "3.12"]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip

{hermes_github_app_plugin-0.1.1 → hermes_github_app_plugin-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hermes-github-app-plugin
-Version: 0.1.1
+Version: 0.2.0
 Summary: Hermes plugin for per-agent GitHub App identity, gh/git wrappers, and GitHub App-aware tools.
 Author: Hermes GitHub App Plugin Contributors
 License: MIT
@@ -26,7 +26,12 @@ Each Hermes agent runs the same package but is configured with its own GitHub Ap
 ```yaml
 github_app:
   client_id: "Iv1.exampleclientid"
+  # Optional default used when a command cannot infer OWNER/REPO.
   installation_id: "987654"
+  # Optional owner-specific installation IDs for apps installed in multiple orgs.
+  installation_ids:
+    ExampleOrg: "123456"
+    ExampleInfra: "987654"
   private_key_path: "~/.hermes/secrets/agent-github-app.private-key.pem"
   app_slug: "hermes-agent"
 ```
@@ -35,6 +40,7 @@ Environment variables with the same meaning are also supported:
 
 - `GITHUB_APP_CLIENT_ID`
 - `GITHUB_APP_INSTALLATION_ID`
+- `GITHUB_APP_INSTALLATION_IDS` (JSON object or `OWNER=ID,OWNER2=ID2` mapping)
 - `GITHUB_APP_PRIVATE_KEY_PATH`
 - `GITHUB_APP_PRIVATE_KEY` (PEM contents; useful for CI)
 
@@ -46,7 +52,7 @@ Repository access is controlled by the GitHub App installation scope in GitHub.
 
 `installation_id` identifies one installation of that app on a specific user or organization account. It is required when exchanging the app JWT for an installation access token via `POST /app/installations/{installation_id}/access_tokens`.
 
-In other words: `client_id` answers "which GitHub App is signing this JWT?" while `installation_id` answers "which installed copy of that app should this token act as?" The same GitHub App can have multiple installation IDs if it is installed on multiple accounts.
+In other words: `client_id` answers "which GitHub App is signing this JWT?" while `installation_id` answers "which installed copy of that app should this token act as?" The same GitHub App can have multiple installation IDs if it is installed on multiple accounts. Configure `installation_ids` when one app is installed in multiple organizations; the plugin chooses an owner-specific ID from `--repo OWNER/REPO` or `/repos/OWNER/REPO` REST paths and falls back to `installation_id` when no repository owner is available.
 
 ## Install
 
@@ -72,6 +78,8 @@ For scripted installs, pass flags and skip the network verification until secret
 hermes-github-app setup --non-interactive --skip-verify \
   --client-id Iv1.exampleclientid \
   --installation-id 987654 \
+  --installation-id-for ExampleOrg=123456 \
+  --installation-id-for ExampleInfra=987654 \
   --private-key-path ~/.hermes/secrets/agent-github-app.private-key.pem \
   --app-slug hermes-agent
 ```
@@ -127,8 +135,8 @@ Before the first release, configure PyPI Trusted Publishing for this repository
 Release example:
 
 ```bash
-git tag 0.1.1
-git push origin 0.1.1
+git tag 0.2.0
+git push origin 0.2.0
 ```
 
 Tags like `v0.1.0`, `0.1`, or `0.1.0rc1` will not publish.

{hermes_github_app_plugin-0.1.1 → hermes_github_app_plugin-0.2.0}/README.md

@@ -7,7 +7,12 @@ Each Hermes agent runs the same package but is configured with its own GitHub Ap
 ```yaml
 github_app:
   client_id: "Iv1.exampleclientid"
+  # Optional default used when a command cannot infer OWNER/REPO.
   installation_id: "987654"
+  # Optional owner-specific installation IDs for apps installed in multiple orgs.
+  installation_ids:
+    ExampleOrg: "123456"
+    ExampleInfra: "987654"
   private_key_path: "~/.hermes/secrets/agent-github-app.private-key.pem"
   app_slug: "hermes-agent"
 ```
@@ -16,6 +21,7 @@ Environment variables with the same meaning are also supported:
 
 - `GITHUB_APP_CLIENT_ID`
 - `GITHUB_APP_INSTALLATION_ID`
+- `GITHUB_APP_INSTALLATION_IDS` (JSON object or `OWNER=ID,OWNER2=ID2` mapping)
 - `GITHUB_APP_PRIVATE_KEY_PATH`
 - `GITHUB_APP_PRIVATE_KEY` (PEM contents; useful for CI)
 
@@ -27,7 +33,7 @@ Repository access is controlled by the GitHub App installation scope in GitHub.
 
 `installation_id` identifies one installation of that app on a specific user or organization account. It is required when exchanging the app JWT for an installation access token via `POST /app/installations/{installation_id}/access_tokens`.
 
-In other words: `client_id` answers "which GitHub App is signing this JWT?" while `installation_id` answers "which installed copy of that app should this token act as?" The same GitHub App can have multiple installation IDs if it is installed on multiple accounts.
+In other words: `client_id` answers "which GitHub App is signing this JWT?" while `installation_id` answers "which installed copy of that app should this token act as?" The same GitHub App can have multiple installation IDs if it is installed on multiple accounts. Configure `installation_ids` when one app is installed in multiple organizations; the plugin chooses an owner-specific ID from `--repo OWNER/REPO` or `/repos/OWNER/REPO` REST paths and falls back to `installation_id` when no repository owner is available.
 
 ## Install
 
@@ -53,6 +59,8 @@ For scripted installs, pass flags and skip the network verification until secret
 hermes-github-app setup --non-interactive --skip-verify \
   --client-id Iv1.exampleclientid \
   --installation-id 987654 \
+  --installation-id-for ExampleOrg=123456 \
+  --installation-id-for ExampleInfra=987654 \
   --private-key-path ~/.hermes/secrets/agent-github-app.private-key.pem \
   --app-slug hermes-agent
 ```
@@ -108,8 +116,8 @@ Before the first release, configure PyPI Trusted Publishing for this repository
 Release example:
 
 ```bash
-git tag 0.1.1
-git push origin 0.1.1
+git tag 0.2.0
+git push origin 0.2.0
 ```
 
 Tags like `v0.1.0`, `0.1`, or `0.1.0rc1` will not publish.

{hermes_github_app_plugin-0.1.1 → hermes_github_app_plugin-0.2.0}/plugin.yaml

@@ -20,7 +20,10 @@ requires_env:
     description: "GitHub App client ID for this Hermes agent. Can also be set in ~/.hermes/config.yaml under github_app.client_id."
     secret: false
   - name: GITHUB_APP_INSTALLATION_ID
-    description: "GitHub App installation ID for this Hermes agent. Can also be set in ~/.hermes/config.yaml under github_app.installation_id."
+    description: "Default GitHub App installation ID for this Hermes agent. Can also be set in ~/.hermes/config.yaml under github_app.installation_id."
+    secret: false
+  - name: GITHUB_APP_INSTALLATION_IDS
+    description: "Optional owner-to-installation-ID mapping for apps installed in multiple orgs. JSON object or OWNER=ID,OWNER2=ID2. Can also be set under github_app.installation_ids."
     secret: false
   - name: GITHUB_APP_PRIVATE_KEY_PATH
     description: "Path to the GitHub App private key PEM. Can also be set in ~/.hermes/config.yaml under github_app.private_key_path."

{hermes_github_app_plugin-0.1.1 → hermes_github_app_plugin-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hermes-github-app-plugin"
-version = "0.1.1"
+version = "0.2.0"
 description = "Hermes plugin for per-agent GitHub App identity, gh/git wrappers, and GitHub App-aware tools."
 readme = "README.md"
 requires-python = ">=3.10"

{hermes_github_app_plugin-0.1.1/src/hermes_github_app_plugin → hermes_github_app_plugin-0.2.0}/skills/github-app-workflow/SKILL.md

@@ -11,7 +11,17 @@ Use this skill for GitHub operations from Hermes agents that are configured with
 
 ## First-time setup
 
-Run `hermes-github-app setup` to write `github_app` config into `~/.hermes/config.yaml`. The setup walkthrough marks optional values with `(optional)`; the required values are GitHub App client ID, installation ID, and private key path.
+Run `hermes-github-app setup` to write `github_app` config into `~/.hermes/config.yaml`. The setup walkthrough marks optional values with `(optional)`; the required values are GitHub App client ID, a default installation ID or owner-specific `installation_ids`, and private key path. For apps installed in multiple organizations, pass repeated `--installation-id-for OWNER=ID` flags or configure:
+
+```yaml
+github_app:
+  installation_id: "123456"  # default/fallback
+  installation_ids:
+    ExampleOrg: "123456"
+    ExampleInfra: "789012"
+```
+
+The plugin chooses an owner-specific installation ID from `--repo OWNER/REPO` or `/repos/OWNER/REPO` REST API paths and falls back to `installation_id` when no repository owner is available.
 
 After setup, run `hermes-github-app doctor --repo OWNER/REPO` to verify console scripts, config loading, private-key permissions, token minting, and repository access. Use `--skip-network` only for container/image builds where secrets or network access are not available yet.
 

{hermes_github_app_plugin-0.1.1 → hermes_github_app_plugin-0.2.0}/src/hermes_github_app_plugin/auth.py

@@ -2,10 +2,12 @@
 
 from __future__ import annotations
 
+import re
 import time
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
 from typing import Any
+from urllib.parse import urlparse
 
 import httpx
 import jwt
@@ -39,7 +41,7 @@ class GitHubAppAuth:
     def __init__(self, config: GitHubAppConfig, client: httpx.Client | None = None) -> None:
         self._config = config
         self._client = client or httpx.Client(timeout=20)
-        self._cached_token: InstallationToken | None = None
+        self._cached_tokens: dict[str, InstallationToken] = {}
 
     @property
     def config(self) -> GitHubAppConfig:
@@ -52,18 +54,21 @@ class GitHubAppAuth:
         encoded = jwt.encode(payload, self._config.private_key, algorithm="RS256")
         return str(encoded)
 
-    def get_installation_token(self, *, force_refresh: bool = False) -> InstallationToken:
+    def get_installation_token(
+        self, *, repo: str | None = None, force_refresh: bool = False
+    ) -> InstallationToken:
         """Return a valid installation token, refreshing when near expiry."""
+        installation_id = self._config.installation_id_for_repo(repo)
+        cached_token = self._cached_tokens.get(installation_id)
         if (
             not force_refresh
-            and self._cached_token is not None
-            and self._cached_token.expires_at > datetime.now(timezone.utc) + timedelta(minutes=5)
+            and cached_token is not None
+            and cached_token.expires_at > datetime.now(timezone.utc) + timedelta(minutes=5)
         ):
-            return self._cached_token
+            return cached_token
 
         response = self._client.post(
-            f"{self._config.github_api_url}/app/installations/"
-            f"{self._config.installation_id}/access_tokens",
+            f"{self._config.github_api_url}/app/installations/{installation_id}/access_tokens",
             headers={
                 "Accept": "application/vnd.github+json",
                 "Authorization": f"Bearer {self.create_jwt()}",
@@ -77,13 +82,54 @@ class GitHubAppAuth:
         token = InstallationToken(
             token=str(data["token"]),
             expires_at=expires_at,
-            installation_id=self._config.installation_id,
+            installation_id=installation_id,
             client_id=self._config.client_id,
             app_slug=self._config.app_slug,
         )
-        self._cached_token = token
+        self._cached_tokens[installation_id] = token
         return token
 
+    def app_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Call a GitHub App endpoint using the app JWT.
+
+        Endpoints like `GET /app` authenticate as the GitHub App itself and
+        reject installation access tokens. Repository and user endpoints should
+        continue to use `request()`, which authenticates as the installation.
+        """
+        url = (
+            path if path.startswith("http") else f"{self._config.github_api_url}/{path.lstrip('/')}"
+        )
+        response = self._client.request(
+            method.upper(),
+            url,
+            headers={
+                "Accept": "application/vnd.github+json",
+                "Authorization": f"Bearer {self.create_jwt()}",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+            json=json_body,
+            params=params,
+        )
+        response.raise_for_status()
+        return {
+            "auth": {
+                "auth_mode": "github_app_jwt",
+                "client_id": self._config.client_id,
+                "app_slug": self._config.app_slug,
+                "installation_id": self._config.installation_id,
+                "installation_ids": dict(self._config.installation_ids),
+            },
+            "status_code": response.status_code,
+            "result": response.json() if response.content else {"ok": True},
+        }
+
     def request(
         self,
         method: str,
@@ -94,7 +140,8 @@ class GitHubAppAuth:
         params: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         """Call the GitHub REST API using the installation token."""
-        token = self.get_installation_token()
+        repo = repo or repo_from_path(path)
+        token = self.get_installation_token(repo=repo)
         url = (
             path if path.startswith("http") else f"{self._config.github_api_url}/{path.lstrip('/')}"
         )
@@ -117,9 +164,11 @@ class GitHubAppAuth:
             "result": parsed,
         }
 
-    def graphql(self, query: str, variables: dict[str, Any] | None = None) -> dict[str, Any]:
+    def graphql(
+        self, query: str, variables: dict[str, Any] | None = None, *, repo: str | None = None
+    ) -> dict[str, Any]:
         """Call GitHub GraphQL API using the installation token."""
-        token = self.get_installation_token()
+        token = self.get_installation_token(repo=repo)
         response = self._client.post(
             f"{self._config.github_api_url}/graphql",
             headers={
@@ -131,7 +180,7 @@ class GitHubAppAuth:
         )
         response.raise_for_status()
         return {
-            "auth": auth_metadata(token),
+            "auth": auth_metadata(token, repo=repo),
             "status_code": response.status_code,
             "result": response.json(),
         }
@@ -150,3 +199,29 @@ def auth_metadata(token: InstallationToken, *, repo: str | None = None) -> dict[
         "token": token.redacted,
         "expires_at": token.expires_at.isoformat(),
     }
+
+
+def requires_app_jwt(path: str) -> bool:
+    """Return True for GitHub App endpoints that require app JWT auth."""
+    path_only = path.split("?", 1)[0]
+    if path_only.startswith("http"):
+        try:
+            path_only = urlparse(path_only).path
+        except ValueError:
+            return False
+    normalized = "/" + path_only.lstrip("/")
+    return normalized == "/app" or normalized.startswith("/app/")
+
+
+def repo_from_path(path: str) -> str | None:
+    """Infer OWNER/REPO from common REST API repository paths."""
+    path_only = path.split("?", 1)[0]
+    if path_only.startswith("http"):
+        try:
+            path_only = urlparse(path_only).path
+        except ValueError:
+            return None
+    match = re.match(r"^/?repos/([^/]+)/([^/]+)(?:/|$)", path_only)
+    if not match:
+        return None
+    return f"{match.group(1)}/{match.group(2)}"

{hermes_github_app_plugin-0.1.1 → hermes_github_app_plugin-0.2.0}/src/hermes_github_app_plugin/cli.py

@@ -15,7 +15,7 @@ from typing import Any, NoReturn
 
 import httpx
 
-from .auth import GitHubAppAuth, auth_metadata
+from .auth import GitHubAppAuth, auth_metadata, requires_app_jwt
 from .config import ConfigurationError, load_config, write_github_app_config
 
 
@@ -29,7 +29,14 @@ def register_cli(parser: argparse.ArgumentParser) -> None:
         "--non-interactive", action="store_true", help="Read values from flags/env only"
     )
     setup.add_argument("--client-id", help="GitHub App client ID")
-    setup.add_argument("--installation-id", help="GitHub App installation ID")
+    setup.add_argument("--installation-id", help="Default GitHub App installation ID")
+    setup.add_argument(
+        "--installation-id-for",
+        action="append",
+        default=[],
+        metavar="OWNER=ID",
+        help="Owner-specific installation ID mapping; repeat for multiple orgs",
+    )
     setup.add_argument("--private-key-path", help="Path to GitHub App private key PEM")
     setup.add_argument("--app-slug", help="Optional GitHub App slug, e.g. my-agent")
     setup.add_argument(
@@ -87,9 +94,9 @@ def gh_app_main() -> NoReturn:
         print("usage: gh-app [--repo OWNER/REPO] [--] <gh args...>")
         print("Runs gh with GH_TOKEN/GITHUB_TOKEN set to a GitHub App installation token.")
         raise SystemExit(0)
-    _, child_args = _extract_repo(args)
+    repo, child_args = _extract_repo(args)
     config = load_config()
-    token = GitHubAppAuth(config).get_installation_token()
+    token = GitHubAppAuth(config).get_installation_token(repo=repo)
     env = os.environ.copy()
     env["GH_TOKEN"] = token.token
     env["GITHUB_TOKEN"] = token.token
@@ -102,9 +109,9 @@ def git_app_main() -> NoReturn:
         print("usage: git-app [--repo OWNER/REPO] [--] <git args...>")
         print("Runs git with a temporary askpass helper backed by a GitHub App token.")
         raise SystemExit(0)
-    _, child_args = _extract_repo(sys.argv[1:])
+    repo, child_args = _extract_repo(sys.argv[1:])
     config = load_config()
-    token = GitHubAppAuth(config).get_installation_token()
+    token = GitHubAppAuth(config).get_installation_token(repo=repo)
     with tempfile.TemporaryDirectory(prefix="git-app-") as temp_dir:
         askpass = Path(temp_dir) / "askpass.sh"
         askpass.write_text(
@@ -127,6 +134,7 @@ def _setup(args: argparse.Namespace) -> int:
     """Interactively write GitHub App configuration."""
     print("Hermes GitHub App setup")
     print("Required values are unmarked. Optional prompts include '(optional)'.")
+    installation_ids = _parse_installation_id_for_args(list(args.installation_id_for))
     values = {
         "client_id": _value_or_prompt(
             args.client_id,
@@ -139,9 +147,10 @@ def _setup(args: argparse.Namespace) -> int:
             args.installation_id,
             "GitHub App installation ID",
             env="GITHUB_APP_INSTALLATION_ID",
-            required=True,
+            required=not installation_ids,
             non_interactive=bool(args.non_interactive),
         ),
+        "installation_ids": installation_ids,
         "private_key_path": _value_or_prompt(
             args.private_key_path,
             "GitHub App private key path",
@@ -194,9 +203,9 @@ def _doctor(repo: str | None, *, skip_network: bool) -> int:
             )
         if not skip_network:
             auth = GitHubAppAuth(config)
-            token = auth.get_installation_token(force_refresh=True)
+            token = auth.get_installation_token(repo=repo, force_refresh=True)
             checks.append(("installation token minted", True, token.redacted))
-            app_result = auth.request("GET", "/app")["result"]
+            app_result = auth.app_request("GET", "/app")["result"]
             checks.append(("/app API reachable", True, str(app_result.get("slug", "ok"))))
             if repo:
                 repo_result = auth.request("GET", f"/repos/{repo}", repo=repo)["result"]
@@ -224,8 +233,8 @@ def _doctor(repo: str | None, *, skip_network: bool) -> int:
 def _status(repo: str | None) -> int:
     config = load_config()
     auth = GitHubAppAuth(config)
-    token = auth.get_installation_token(force_refresh=True)
-    app = auth.request("GET", "/app")["result"]
+    token = auth.get_installation_token(repo=repo, force_refresh=True)
+    app = auth.app_request("GET", "/app")["result"]
     repo_probe = auth.request("GET", f"/repos/{repo}", repo=repo)["result"] if repo else None
     print(
         json.dumps(
@@ -244,7 +253,7 @@ def _status(repo: str | None) -> int:
 
 def _token(repo: str | None, *, json_output: bool) -> int:
     config = load_config()
-    token = GitHubAppAuth(config).get_installation_token()
+    token = GitHubAppAuth(config).get_installation_token(repo=repo)
     if json_output:
         print(json.dumps({"token": token.token, "auth": auth_metadata(token, repo=repo)}, indent=2))
     else:
@@ -253,11 +262,34 @@ def _token(repo: str | None, *, json_output: bool) -> int:
 
 
 def _api(method: str, path: str, *, repo: str | None, body: dict[str, Any] | None) -> int:
-    result = GitHubAppAuth(load_config()).request(method, path, repo=repo, json_body=body)
+    auth = GitHubAppAuth(load_config())
+    if requires_app_jwt(path):
+        result = auth.app_request(method, path, json_body=body)
+    else:
+        result = auth.request(method, path, repo=repo, json_body=body)
     print(json.dumps(result, indent=2, sort_keys=True))
     return 0
 
 
+def _parse_installation_id_for_args(values: list[str]) -> dict[str, str]:
+    """Parse repeated OWNER=INSTALLATION_ID setup flags."""
+    installation_ids: dict[str, str] = {}
+    for value in values:
+        if "=" not in value:
+            raise ConfigurationError(
+                f"invalid --installation-id-for value: {value!r}; expected OWNER=INSTALLATION_ID"
+            )
+        owner, installation_id = value.split("=", 1)
+        owner = owner.strip().lower()
+        installation_id = installation_id.strip()
+        if not owner or not installation_id:
+            raise ConfigurationError(
+                f"invalid --installation-id-for value: {value!r}; expected OWNER=INSTALLATION_ID"
+            )
+        installation_ids[owner] = installation_id
+    return installation_ids
+
+
 def _value_or_prompt(
     value: str | None,
     label: str,

{hermes_github_app_plugin-0.1.1 → hermes_github_app_plugin-0.2.0}/src/hermes_github_app_plugin/config.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import os
 from collections.abc import Mapping
 from dataclasses import dataclass
@@ -22,10 +23,20 @@ class GitHubAppConfig:
     client_id: str
     installation_id: str
     private_key: str
+    installation_ids: dict[str, str]
     private_key_source: str
     app_slug: str | None = None
     github_api_url: str = "https://api.github.com"
 
+    def installation_id_for_repo(self, repo: str | None = None) -> str:
+        """Return the installation ID for an optional OWNER/REPO target."""
+        if repo and "/" in repo:
+            owner = repo.split("/", 1)[0].lower()
+            installation_id = self.installation_ids.get(owner)
+            if installation_id:
+                return installation_id
+        return self.installation_id
+
 
 def hermes_home() -> Path:
     """Return the configured Hermes home directory."""
@@ -63,7 +74,7 @@ def write_github_app_config(values: Mapping[str, Any]) -> Path:
         section = {}
         data["github_app"] = section
     for key, value in values.items():
-        if value in (None, "", (), []):
+        if value in (None, "", (), []) or (isinstance(value, Mapping) and not value):
             section.pop(key, None)
         else:
             section[key] = value
@@ -76,6 +87,37 @@ def write_github_app_config(values: Mapping[str, Any]) -> Path:
     return path
 
 
+def _parse_installation_ids(raw: Any) -> dict[str, str]:
+    """Parse owner-to-installation-ID mapping from YAML or environment values."""
+    if raw in (None, ""):
+        return {}
+    parsed: Any = raw
+    if isinstance(raw, str):
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            parsed = {}
+            for item in raw.replace("\n", ",").split(","):
+                if not item.strip():
+                    continue
+                if "=" not in item:
+                    raise ConfigurationError(
+                        "invalid GITHUB_APP_INSTALLATION_IDS entry: "
+                        f"{item!r}; expected OWNER=INSTALLATION_ID"
+                    ) from None
+                owner, installation_id = item.split("=", 1)
+                parsed[owner.strip()] = installation_id.strip()
+    if not isinstance(parsed, Mapping):
+        raise ConfigurationError("github_app.installation_ids must be a mapping of owner to ID")
+    result: dict[str, str] = {}
+    for owner, installation_id in parsed.items():
+        owner_text = str(owner).strip().lower()
+        installation_text = str(installation_id).strip()
+        if owner_text and installation_text:
+            result[owner_text] = installation_text
+    return result
+
+
 def _read_private_key(section: Mapping[str, Any]) -> tuple[str, str]:
     inline_key = os.environ.get("GITHUB_APP_PRIVATE_KEY") or str(section.get("private_key", ""))
     if inline_key:
@@ -106,16 +148,23 @@ def load_config() -> GitHubAppConfig:
         raise ConfigurationError(
             "missing GitHub App client ID: set GITHUB_APP_CLIENT_ID or github_app.client_id"
         )
-    if not installation_id:
+    installation_ids = _parse_installation_ids(
+        os.environ.get("GITHUB_APP_INSTALLATION_IDS") or section.get("installation_ids", {})
+    )
+    if not installation_id and not installation_ids:
         raise ConfigurationError(
-            "missing GitHub App installation ID: set GITHUB_APP_INSTALLATION_ID "
-            "or github_app.installation_id"
+            "missing GitHub App installation ID: set GITHUB_APP_INSTALLATION_ID, "
+            "github_app.installation_id, or github_app.installation_ids"
         )
+    if not installation_id:
+        # Use a deterministic fallback for commands that cannot infer an OWNER/REPO.
+        installation_id = next(iter(installation_ids.values()))
     private_key, private_key_source = _read_private_key(section)
     return GitHubAppConfig(
         client_id=client_id,
         installation_id=installation_id,
         private_key=private_key,
+        installation_ids=installation_ids,
         private_key_source=private_key_source,
         app_slug=os.environ.get("GITHUB_APP_SLUG") or section.get("app_slug"),
         github_api_url=os.environ.get("GITHUB_API_URL")

{hermes_github_app_plugin-0.1.1 → hermes_github_app_plugin-0.2.0/src/hermes_github_app_plugin}/skills/github-app-workflow/SKILL.md

@@ -11,7 +11,17 @@ Use this skill for GitHub operations from Hermes agents that are configured with
 
 ## First-time setup
 
-Run `hermes-github-app setup` to write `github_app` config into `~/.hermes/config.yaml`. The setup walkthrough marks optional values with `(optional)`; the required values are GitHub App client ID, installation ID, and private key path.
+Run `hermes-github-app setup` to write `github_app` config into `~/.hermes/config.yaml`. The setup walkthrough marks optional values with `(optional)`; the required values are GitHub App client ID, a default installation ID or owner-specific `installation_ids`, and private key path. For apps installed in multiple organizations, pass repeated `--installation-id-for OWNER=ID` flags or configure:
+
+```yaml
+github_app:
+  installation_id: "123456"  # default/fallback
+  installation_ids:
+    ExampleOrg: "123456"
+    ExampleInfra: "789012"
+```
+
+The plugin chooses an owner-specific installation ID from `--repo OWNER/REPO` or `/repos/OWNER/REPO` REST API paths and falls back to `installation_id` when no repository owner is available.
 
 After setup, run `hermes-github-app doctor --repo OWNER/REPO` to verify console scripts, config loading, private-key permissions, token minting, and repository access. Use `--skip-network` only for container/image builds where secrets or network access are not available yet.
 

{hermes_github_app_plugin-0.1.1 → hermes_github_app_plugin-0.2.0}/src/hermes_github_app_plugin/tools.py

@@ -7,7 +7,7 @@ from typing import Any
 
 import httpx
 
-from .auth import GitHubAppAuth, auth_metadata
+from .auth import GitHubAppAuth, auth_metadata, requires_app_jwt
 from .config import ConfigurationError, load_config
 
 
@@ -39,6 +39,7 @@ def github_app_status(params: dict[str, Any], **_: Any) -> str:
             "configured": True,
             "client_id": config.client_id,
             "installation_id": config.installation_id,
+            "installation_ids": dict(config.installation_ids),
             "app_slug": config.app_slug,
             "private_key_source": config.private_key_source,
             "github_api_url": config.github_api_url,
@@ -54,8 +55,8 @@ def github_app_verify_identity(params: dict[str, Any], **_: Any) -> str:
     def run() -> dict[str, Any]:
         repo = _repo(params)
         auth = _auth()
-        token = auth.get_installation_token(force_refresh=True)
-        app = auth.request("GET", "/app")
+        token = auth.get_installation_token(repo=repo, force_refresh=True)
+        app = auth.app_request("GET", "/app")
         repo_probe = auth.request("GET", f"/repos/{repo}", repo=repo) if repo else None
         return {
             "auth": auth_metadata(token, repo=repo),
@@ -75,7 +76,12 @@ def github_app_api(params: dict[str, Any], **_: Any) -> str:
         repo = _repo(params)
         body = params.get("json_body")
         json_body = body if isinstance(body, dict) else None
-        result = _auth().request(method, path, repo=repo, json_body=json_body)
+        auth = _auth()
+        result = (
+            auth.app_request(method, path, json_body=json_body)
+            if requires_app_jwt(path)
+            else auth.request(method, path, repo=repo, json_body=json_body)
+        )
         return result
 
     return _handle_errors(run)
@@ -87,7 +93,9 @@ def github_app_graphql(params: dict[str, Any], **_: Any) -> str:
     def run() -> dict[str, Any]:
         variables = params.get("variables")
         return _auth().graphql(
-            str(params["query"]), variables if isinstance(variables, dict) else None
+            str(params["query"]),
+            variables if isinstance(variables, dict) else None,
+            repo=_repo(params),
         )
 
     return _handle_errors(run)

hermes_github_app_plugin-0.2.0/tests/test_auth.py

@@ -0,0 +1,143 @@
+"""Tests for GitHub App auth helpers."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+import httpx
+
+from hermes_github_app_plugin.auth import (
+    GitHubAppAuth,
+    InstallationToken,
+    auth_metadata,
+    repo_from_path,
+    requires_app_jwt,
+)
+from hermes_github_app_plugin.config import GitHubAppConfig
+
+PRIVATE_KEY = "[REDACTED PRIVATE KEY]\n"
+
+
+def test_auth_metadata_redacts_token() -> None:
+    token = InstallationToken(
+        token="ghu_ab...wxyz",
+        expires_at=datetime(2030, 1, 1, tzinfo=timezone.utc),
+        installation_id="456",
+        client_id="123",
+        app_slug="hermes-test-agent",
+    )
+
+    metadata = auth_metadata(token, repo="ExampleOrg/example-repo")
+
+    assert metadata["auth_mode"] == "github_app"
+    assert metadata["actor_expected"] == "hermes-test-agent[bot]"
+    assert metadata["token"] == "ghu_…wxyz"
+
+
+def test_request_includes_installation_token(monkeypatch) -> None:  # type: ignore[no-untyped-def]
+    monkeypatch.setattr("jwt.encode", lambda *_, **__: "jwt-token")
+    seen: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        if request.url.path.endswith("/access_tokens"):
+            return httpx.Response(
+                201,
+                json={"token": "ghu_installation_token", "expires_at": "2030-01-01T00:00:00Z"},
+            )
+        return httpx.Response(200, json={"full_name": "ExampleOrg/example-repo"})
+
+    client = httpx.Client(transport=httpx.MockTransport(handler))
+    config = GitHubAppConfig(
+        client_id="123",
+        installation_id="456",
+        private_key=PRIVATE_KEY,
+        installation_ids={},
+        private_key_source="env",
+        app_slug="hermes-test-agent",
+    )
+
+    result = GitHubAppAuth(config, client=client).request(
+        "GET", "/repos/ExampleOrg/example-repo", repo="ExampleOrg/example-repo"
+    )
+
+    assert result["result"] == {"full_name": "ExampleOrg/example-repo"}
+    assert seen[0].headers["authorization"] == "Bearer jwt-token"
+    assert seen[1].headers["authorization"] == "Bearer ghu_installation_token"
+    assert json.loads(json.dumps(result))["auth"]["auth_mode"] == "github_app"
+
+
+def test_app_request_uses_app_jwt(monkeypatch) -> None:  # type: ignore[no-untyped-def]
+    monkeypatch.setattr("jwt.encode", lambda *_, **__: "jwt-token")
+    seen: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        return httpx.Response(200, json={"slug": "hermes-test-agent"})
+
+    client = httpx.Client(transport=httpx.MockTransport(handler))
+    config = GitHubAppConfig(
+        client_id="123",
+        installation_id="456",
+        private_key=PRIVATE_KEY,
+        installation_ids={},
+        private_key_source="env",
+        app_slug="hermes-test-agent",
+    )
+
+    result = GitHubAppAuth(config, client=client).app_request("GET", "/app")
+
+    assert result["result"] == {"slug": "hermes-test-agent"}
+    assert seen[0].url.path == "/app"
+    assert seen[0].headers["authorization"] == "Bearer jwt-token"
+    assert result["auth"]["auth_mode"] == "github_app_jwt"
+
+
+def test_requires_app_jwt_detects_app_endpoints() -> None:
+    assert requires_app_jwt("/app")
+    assert requires_app_jwt("/app/installations")
+    assert requires_app_jwt("https://api.github.com/app")
+    assert not requires_app_jwt("/repos/OWNER/REPO")
+
+
+def test_request_chooses_installation_id_for_repo_owner(monkeypatch) -> None:  # type: ignore[no-untyped-def]
+    monkeypatch.setattr("jwt.encode", lambda *_, **__: "jwt-token")
+    token_paths: list[str] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.url.path.endswith("/access_tokens"):
+            token_paths.append(request.url.path)
+            installation_id = request.url.path.split("/")[-2]
+            return httpx.Response(
+                201,
+                json={
+                    "token": f"ghu_token_{installation_id}",
+                    "expires_at": "2030-01-01T00:00:00Z",
+                },
+            )
+        return httpx.Response(200, json={"full_name": "ExampleInfra/automation-config"})
+
+    client = httpx.Client(transport=httpx.MockTransport(handler))
+    config = GitHubAppConfig(
+        client_id="123",
+        installation_id="456",
+        private_key=PRIVATE_KEY,
+        installation_ids={"exampleinfra": "789"},
+        private_key_source="env",
+        app_slug="hermes-test-agent",
+    )
+
+    result = GitHubAppAuth(config, client=client).request(
+        "GET", "/repos/ExampleInfra/automation-config"
+    )
+
+    assert token_paths == ["/app/installations/789/access_tokens"]
+    assert result["auth"]["installation_id"] == "789"
+    assert result["auth"]["repository"] == "ExampleInfra/automation-config"
+
+
+def test_repo_from_path_infers_rest_repo_paths() -> None:
+    assert repo_from_path("/repos/OWNER/REPO/issues") == "OWNER/REPO"
+    assert repo_from_path("https://api.github.com/repos/OWNER/REPO") == "OWNER/REPO"
+    assert repo_from_path("/installation/repositories") is None

{hermes_github_app_plugin-0.1.1 → hermes_github_app_plugin-0.2.0}/tests/test_cli.py

@@ -26,6 +26,7 @@ def test_setup_non_interactive_writes_config_and_skips_verify(
         github_app_command="setup",
         client_id="Iv1.exampleclientid",
         installation_id="987654",
+        installation_id_for=[],
         private_key_path=str(key_path),
         app_slug="hermes-test-agent",
         non_interactive=True,
@@ -65,6 +66,7 @@ def test_setup_prompts_mark_optional(
         github_app_command="setup",
         client_id=None,
         installation_id=None,
+        installation_id_for=[],
         private_key_path=None,
         app_slug=None,
         non_interactive=False,
@@ -88,7 +90,7 @@ def test_doctor_skip_network_reports_local_checks(
     key_path.write_text(PRIVATE_KEY, encoding="utf-8")
     key_path.chmod(0o600)
     monkeypatch.setenv("HERMES_HOME", str(hermes_home))
-    (hermes_home).mkdir()
+    hermes_home.mkdir()
     (hermes_home / "config.yaml").write_text(
         f"""
 github_app:
@@ -106,3 +108,85 @@ github_app:
     assert "✓ GitHub App config loaded" in output
     assert "✓ private key file permissions: 0o600" in output
     assert "Local doctor passed" in output
+
+
+def test_api_routes_app_paths_to_app_jwt(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    class FakeAuth:
+        def __init__(self, config: object) -> None:
+            self.config = config
+
+        def app_request(
+            self, method: str, path: str, json_body: dict[str, object] | None = None
+        ) -> dict[str, object]:
+            return {"status_code": 200, "result": {"path": path, "method": method}}
+
+        def request(self, *args: object, **kwargs: object) -> dict[str, object]:
+            raise AssertionError("installation-token request should not be used for /app")
+
+    monkeypatch.setattr(cli, "load_config", object)
+    monkeypatch.setattr(cli, "GitHubAppAuth", FakeAuth)
+
+    assert cli._api("GET", "/app", repo=None, body=None) == 0
+
+    output = capsys.readouterr().out
+    assert '"status_code": 200' in output
+
+
+def test_api_routes_repo_paths_to_installation_token(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    class FakeAuth:
+        def __init__(self, config: object) -> None:
+            self.config = config
+
+        def app_request(self, *args: object, **kwargs: object) -> dict[str, object]:
+            raise AssertionError("app JWT request should not be used for repo APIs")
+
+        def request(
+            self,
+            method: str,
+            path: str,
+            repo: str | None = None,
+            json_body: dict[str, object] | None = None,
+        ) -> dict[str, object]:
+            return {"status_code": 200, "result": {"path": path, "repo": repo, "method": method}}
+
+    monkeypatch.setattr(cli, "load_config", object)
+    monkeypatch.setattr(cli, "GitHubAppAuth", FakeAuth)
+
+    assert cli._api("GET", "/repos/OWNER/REPO", repo="OWNER/REPO", body=None) == 0
+
+    output = capsys.readouterr().out
+    assert '"repo": "OWNER/REPO"' in output
+
+
+def test_setup_non_interactive_writes_owner_installation_ids(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    hermes_home = tmp_path / ".hermes"
+    key_path = tmp_path / "app.pem"
+    key_path.write_text(PRIVATE_KEY, encoding="utf-8")
+    key_path.chmod(0o600)
+    monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+
+    args = argparse.Namespace(
+        github_app_command="setup",
+        client_id="Iv1.exampleclientid",
+        installation_id="987654",
+        installation_id_for=["ExampleOrg=111", "ExampleInfra=222"],
+        private_key_path=str(key_path),
+        app_slug="hermes-test-agent",
+        non_interactive=True,
+        repo=None,
+        skip_verify=True,
+    )
+
+    assert cli.main(args) == 0
+
+    data = yaml.safe_load((hermes_home / "config.yaml").read_text(encoding="utf-8"))
+    assert data["github_app"]["installation_ids"] == {
+        "exampleorg": "111",
+        "exampleinfra": "222",
+    }

{hermes_github_app_plugin-0.1.1 → hermes_github_app_plugin-0.2.0}/tests/test_config.py

@@ -20,6 +20,7 @@ def test_load_config_from_environment(monkeypatch: pytest.MonkeyPatch) -> None:
 
     assert config.client_id == "123"
     assert config.installation_id == "456"
+    assert config.installation_ids == {}
     assert config.private_key == PRIVATE_KEY
 
 
@@ -33,6 +34,9 @@ def test_load_config_from_hermes_yaml(tmp_path: Path, monkeypatch: pytest.Monkey
 github_app:
   client_id: 111
   installation_id: 222
+  installation_ids:
+    ExampleOrg: 333
+    ExampleInfra: 444
   private_key_path: {key_path}
   app_slug: hermes-test-agent
 """,
@@ -48,4 +52,25 @@ github_app:
 
     assert config.client_id == "111"
     assert config.installation_id == "222"
+    assert config.installation_ids == {"exampleorg": "333", "exampleinfra": "444"}
+    assert config.installation_id_for_repo("ExampleOrg/example-repo") == "333"
+    assert config.installation_id_for_repo("ExampleInfra/automation-config") == "444"
+    assert config.installation_id_for_repo("Other/repo") == "222"
     assert config.app_slug == "hermes-test-agent"
+
+
+def test_load_config_installation_ids_from_environment(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("GITHUB_APP_CLIENT_ID", "123")
+    monkeypatch.setenv("GITHUB_APP_INSTALLATION_IDS", "ExampleOrg=456,ExampleInfra=789")
+    monkeypatch.setenv("GITHUB_APP_PRIVATE_KEY", PRIVATE_KEY)
+    monkeypatch.delenv("GITHUB_APP_INSTALLATION_ID", raising=False)
+    hermes_home = tmp_path / ".hermes"
+    hermes_home.mkdir()
+    monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+
+    config = load_config()
+
+    assert config.installation_id == "456"
+    assert config.installation_id_for_repo("ExampleInfra/automation-config") == "789"

hermes_github_app_plugin-0.1.1/tests/test_auth.py

@@ -1,61 +0,0 @@
-"""Tests for GitHub App auth helpers."""
-
-from __future__ import annotations
-
-import json
-from datetime import datetime, timezone
-
-import httpx
-
-from hermes_github_app_plugin.auth import GitHubAppAuth, InstallationToken, auth_metadata
-from hermes_github_app_plugin.config import GitHubAppConfig
-
-PRIVATE_KEY = "[REDACTED PRIVATE KEY]\n"
-
-
-def test_auth_metadata_redacts_token() -> None:
-    token = InstallationToken(
-        token="ghu_ab...wxyz",
-        expires_at=datetime(2030, 1, 1, tzinfo=timezone.utc),
-        installation_id="456",
-        client_id="123",
-        app_slug="hermes-test-agent",
-    )
-
-    metadata = auth_metadata(token, repo="ExampleOrg/example-repo")
-
-    assert metadata["auth_mode"] == "github_app"
-    assert metadata["actor_expected"] == "hermes-test-agent[bot]"
-    assert metadata["token"] == "ghu_…wxyz"
-
-
-def test_request_includes_installation_token(monkeypatch) -> None:  # type: ignore[no-untyped-def]
-    monkeypatch.setattr("jwt.encode", lambda *_, **__: "jwt-token")
-    seen: list[httpx.Request] = []
-
-    def handler(request: httpx.Request) -> httpx.Response:
-        seen.append(request)
-        if request.url.path.endswith("/access_tokens"):
-            return httpx.Response(
-                201,
-                json={"token": "ghu_installation_token", "expires_at": "2030-01-01T00:00:00Z"},
-            )
-        return httpx.Response(200, json={"full_name": "ExampleOrg/example-repo"})
-
-    client = httpx.Client(transport=httpx.MockTransport(handler))
-    config = GitHubAppConfig(
-        client_id="123",
-        installation_id="456",
-        private_key=PRIVATE_KEY,
-        private_key_source="env",
-        app_slug="hermes-test-agent",
-    )
-
-    result = GitHubAppAuth(config, client=client).request(
-        "GET", "/repos/ExampleOrg/example-repo", repo="ExampleOrg/example-repo"
-    )
-
-    assert result["result"] == {"full_name": "ExampleOrg/example-repo"}
-    assert seen[0].headers["authorization"] == "Bearer jwt-token"
-    assert seen[1].headers["authorization"] == "Bearer ghu_installation_token"
-    assert json.loads(json.dumps(result))["auth"]["auth_mode"] == "github_app"