feat: support gateway-managed GitHub App installation tokens

[grs]

User Story

As an OpenShell operator, I want the gateway to mint and rotate scoped GitHub App installation tokens, so that sandboxed agents can access approved repositories without receiving a long-lived personal token or the app’s private key.

Problem Statement

OpenShell does not provide a gateway-managed authentication flow for GitHub App installations. Operators must currently use a personal access token, inject a pre-minted installation token, or operate an external token-minting and rotation service.

GitHub installation tokens are short-lived and require an app JWT signed with the app’s private key. Using a static installation token does not provide reliable rotation.

Impact / Why This Matters

GitHub Apps are the preferred authentication model for automated repository access because they support narrowly scoped repository and permission grants without relying on a user identity.

Without native support:

• Operators must manage token minting and renewal outside OpenShell.
• Static installation tokens expire and interrupt long-running workloads.
• Personal access tokens may be longer-lived, broader in scope, and tied to a human identity.
• External rotation adds deployment, synchronization, and failure-handling complexity.
• Exposing the app private key to a workload would allow it to mint additional tokens outside the intended OpenShell policy boundary.

Proposed Design

Add a gateway-managed github_app_installation provider refresh strategy and an example github-app provider profile.

The user-facing workflow should allow an operator to:

1. Import the GitHub App provider profile.
2. Create a provider using runtime credentials.
3. Configure refresh with:
   • GitHub App client ID
   • Installation ID
   • RSA private key supplied as secret material
   • An explicit list of repository IDs
   • An explicit permission map
4. Optionally rotate once to verify the configuration and check refresh status.
5. Attach the provider to a sandbox.

The gateway should retain the private key, sign the app JWT, request a scoped installation token, and expose only the resulting short-lived token through either GITHUB_TOKEN or GH_TOKEN.

Acceptance Criteria

• The public API, CLI, TUI, provider profile format, and Go SDK recognize github_app_installation as a gateway-mintable refresh strategy.
• An example github-app profile supports runtime credentials and GitHub API and HTTPS Git access.
• Refresh configuration requires a client ID, positive installation ID, valid RSA PEM private key, explicit repository IDs, and explicit permissions.
• Permissions are nonempty and use GitHub permission names with read, write, or admin levels. OAuth scopes are not accepted as a substitute.
• The app private key remains in the gateway credential backend, and neither the key nor the signed app JWT is exposed to the sandbox.
• The minted installation token is injected through exactly one selected alias: GITHUB_TOKEN or GH_TOKEN.
• The logical credential name api_token resolves to the configured alias, defaulting to GITHUB_TOKEN when no alias is configured.
• A second refresh configuration under the sibling alias is rejected, including while the existing configuration is pending or failed.
• Refresh status and deletion remain usable to diagnose and remove legacy or conflicting alias state.
• Explicit rotation and scheduled refresh preserve active workload handles during routine token rotation.
• Expired credentials fail closed.
• End-to-end test coverage.

Alternatives Considered

Use a personal access token

This is simpler, but it ties automation to a user identity and may provide broader or longer-lived access than required.

Store a pre-minted installation token as a static credential

Installation tokens are short-lived. Static storage does not provide automatic renewal and will eventually interrupt the workload.

Require an external refresh process

OpenShell’s external refresh mechanism can support custom integrations, but it requires operators to deploy and synchronize another service. A native strategy provides a consistent configure, rotate, status, and failure-recovery workflow.

Extend the existing static GitHub profile

GITHUB_TOKEN and GH_TOKEN can contain personal, OAuth, or installation tokens. Keeping a distinct GitHub App profile makes the required setup and security properties explicit instead of inferring authentication type from an environment-variable name.

Agent Investigation

No response

Checklist

• I've reviewed existing issues and the published docs
• This is a design proposal, not a "please build this" request