feat(provider): add a refresh strategy for github app installations

Signed-off-by: Gordon Sim <gsim@redhat.com>

Author: grs

CI.md

@@ -34,6 +34,20 @@ The GitHub ruleset should require the `OpenShell / ...` statuses published by
 `Required CI Gates` plus the direct `OpenShell / Trivy Changes` result, not the
 push-triggered workflow jobs themselves.
 
+The GitHub App sandbox regression is independently selectable:
+
+```shell
+OPENSHELL_E2E_PODMAN_TEST=provider_github_app mise run e2e:podman
+```
+
+It builds a tool image with `gh` and Git, then uses a local installation-token
+issuer and authenticated HTTPS API/Git fixture. It checks both clients across
+12 rotations, revocation after reconfiguration, and a fresh process using the
+replacement handle. No live GitHub app or installation is required. It needs
+the wrapper-managed gateway so it can temporarily trust the fixture CA; the
+original gateway configuration is restored afterward. The OAuth counterpart
+remains separately selectable as `provider_refresh_handles`.
+
 ## Informational security reports
 
 Security workflow compute runs directly on GitHub-hosted runners instead of

architecture/build.md

@@ -108,6 +108,12 @@ test identity and tools, with Python aligned to the host test runner for
 serialized callable compatibility. Default-image coverage retains the product
 image. Other compute-driver test lanes retain their existing workload fixtures.
 
+The Podman E2E gateway pins both the supervisor and sandbox runtime images
+selected by its wrapper, so a local test cannot mix a checkout's supervisor
+with a registry-default sandbox runtime. GitHub App credential tests run as a
+separate target with a local HTTPS API and Git backend, ephemeral CA trust, and
+real workload clients; they require no live GitHub credentials.
+
 The Docker image pipeline is a two-step flow: build the Rust binary natively
 for the target architecture, then assemble the container image from the
 prebuilt binary. The gateway, sandbox, and supervisor images use distinct

architecture/gateway.md

@@ -788,6 +788,19 @@ credential storage for defense in depth. Multi-replica deployments can use that
 default with a shared database and shared key-encryption key, or opt into an
 external backend such as Vault or Kubernetes Secrets.
 
+GitHub App installation refresh signs an app JWT at the gateway and exchanges it
+for an installation token using a profile-owned endpoint. Each provider pins one
+installation and explicit repository IDs and permissions in its refresh material;
+there is no workload-selected scope or installation-wide default. The app key is
+secret material, and only the installation token enters the existing credential
+distribution path. Refresh honors the issuer expiry, caps local use at one hour,
+and preserves the existing authorization epoch during routine rotation. Explicit
+reconfiguration revokes the old workload handles. Network policy remains an
+independent constraint on token use. GitHub mint failures use gateway-owned
+recovery classifications without storing issuer-controlled error prose.
+Transport diagnostics classify typed timeout, TLS, and connection failures
+without exposing request material or raw error chains.
+
 The Vault credential driver requires HTTPS for every non-loopback backend,
 never follows HTTP redirects, and keeps standard certificate hostname
 verification enabled. Operators can add private Vault trust roots with a PEM

crates/openshell-cli/src/commands/common.rs

@@ -1180,13 +1180,15 @@ mod tests {
         assert_eq!(prof[0].0, "GITHUB_TOKEN");
 
         let sug = &prof[0].1;
-        assert_eq!(sug.len(), 2_usize);
+        assert_eq!(sug.len(), 3_usize);
 
         assert_eq!(sug[0].provider_type, "copilot");
         assert_eq!(sug[0].credential, "api_token");
 
         assert_eq!(sug[1].provider_type, "github");
         assert_eq!(sug[1].credential, "api_token");
+        assert_eq!(sug[2].provider_type, "github-app");
+        assert_eq!(sug[2].credential, "api_token");
     }
 
     #[test]
@@ -1198,13 +1200,15 @@ mod tests {
         assert_eq!(prof[0].0, "gh_token");
 
         let sug = &prof[0].1;
-        assert_eq!(sug.len(), 2_usize);
+        assert_eq!(sug.len(), 3_usize);
 
         assert_eq!(sug[0].provider_type, "copilot");
         assert_eq!(sug[0].credential, "api_token");
 
         assert_eq!(sug[1].provider_type, "github");
         assert_eq!(sug[1].credential, "api_token");
+        assert_eq!(sug[2].provider_type, "github-app");
+        assert_eq!(sug[2].credential, "api_token");
     }
 
     #[test]

crates/openshell-cli/src/commands/provider.rs

@@ -2063,6 +2063,7 @@ fn provider_refresh_strategy(strategy: &str) -> Result<ProviderCredentialRefresh
             Ok(ProviderCredentialRefreshStrategy::GoogleServiceAccountJwt)
         }
         "aws_sts_assume_role" => Ok(ProviderCredentialRefreshStrategy::AwsStsAssumeRole),
+        "github_app_installation" => Ok(ProviderCredentialRefreshStrategy::GithubAppInstallation),
         _ => Err(miette!("unsupported provider refresh strategy: {strategy}")),
     }
 }
@@ -2114,6 +2115,7 @@ fn provider_refresh_strategy_name(strategy: ProviderCredentialRefreshStrategy) -
         ProviderCredentialRefreshStrategy::Oauth2ClientCredentials => "oauth2_client_credentials",
         ProviderCredentialRefreshStrategy::GoogleServiceAccountJwt => "google_service_account_jwt",
         ProviderCredentialRefreshStrategy::AwsStsAssumeRole => "aws_sts_assume_role",
+        ProviderCredentialRefreshStrategy::GithubAppInstallation => "github_app_installation",
         ProviderCredentialRefreshStrategy::Unspecified => "unspecified",
     }
 }

crates/openshell-cli/src/main.rs

@@ -776,6 +776,7 @@ enum CliProviderRefreshStrategy {
     Oauth2ClientCredentials,
     GoogleServiceAccountJwt,
     AwsStsAssumeRole,
+    GithubAppInstallation,
 }
 
 impl CliProviderRefreshStrategy {
@@ -785,6 +786,7 @@ impl CliProviderRefreshStrategy {
             Self::Oauth2ClientCredentials => "oauth2_client_credentials",
             Self::GoogleServiceAccountJwt => "google_service_account_jwt",
             Self::AwsStsAssumeRole => "aws_sts_assume_role",
+            Self::GithubAppInstallation => "github_app_installation",
         }
     }
 }
@@ -5625,6 +5627,39 @@ mod tests {
         assert!(msg.contains("--from-gcloud-adc"));
     }
 
+    #[test]
+    fn github_app_refresh_command_parses() {
+        let config = Cli::try_parse_from([
+            "openshell",
+            "provider",
+            "refresh",
+            "configure",
+            "repo-reader",
+            "--credential-key",
+            "GITHUB_TOKEN",
+            "--strategy",
+            "github-app-installation",
+            "--material",
+            "repository_ids=[42]",
+            "--material",
+            "permissions={\"contents\":\"read\"}",
+            "--secret-material-env",
+            "private_key=GITHUB_APP_PRIVATE_KEY",
+        ])
+        .expect("GitHub App refresh configuration should parse");
+        assert!(matches!(
+            config.command,
+            Some(Commands::Provider {
+                command: Some(ProviderCommands::Refresh(
+                    ProviderRefreshCommands::Configure {
+                        strategy: CliProviderRefreshStrategy::GithubAppInstallation,
+                        ..
+                    }
+                ))
+            })
+        ));
+    }
+
     #[test]
     fn provider_refresh_commands_parse() {
         let status = Cli::try_parse_from([

crates/openshell-providers/src/profiles.rs

@@ -1063,6 +1063,7 @@ pub fn is_gateway_mintable_strategy(strategy: ProviderCredentialRefreshStrategy)
             | ProviderCredentialRefreshStrategy::Oauth2ClientCredentials
             | ProviderCredentialRefreshStrategy::GoogleServiceAccountJwt
             | ProviderCredentialRefreshStrategy::AwsStsAssumeRole
+            | ProviderCredentialRefreshStrategy::GithubAppInstallation
     )
 }
 
@@ -1313,6 +1314,7 @@ pub fn provider_refresh_strategy_from_yaml(raw: &str) -> Option<ProviderCredenti
             Some(ProviderCredentialRefreshStrategy::GoogleServiceAccountJwt)
         }
         "aws_sts_assume_role" => Some(ProviderCredentialRefreshStrategy::AwsStsAssumeRole),
+        "github_app_installation" => Some(ProviderCredentialRefreshStrategy::GithubAppInstallation),
         _ => None,
     }
 }
@@ -1328,6 +1330,7 @@ pub fn provider_refresh_strategy_to_yaml(
         ProviderCredentialRefreshStrategy::Oauth2ClientCredentials => "oauth2_client_credentials",
         ProviderCredentialRefreshStrategy::GoogleServiceAccountJwt => "google_service_account_jwt",
         ProviderCredentialRefreshStrategy::AwsStsAssumeRole => "aws_sts_assume_role",
+        ProviderCredentialRefreshStrategy::GithubAppInstallation => "github_app_installation",
         ProviderCredentialRefreshStrategy::Unspecified => "unspecified",
     }
 }
@@ -2198,6 +2201,20 @@ pub fn validate_profile_set(
             }
 
             if let Some(refresh) = credential.refresh.as_ref() {
+                if refresh.strategy == ProviderCredentialRefreshStrategy::GithubAppInstallation
+                    && (!refresh
+                        .token_url
+                        .ends_with("/app/installations/{installation_id}/access_tokens")
+                        || refresh.token_url.matches("{installation_id}").count() != 1
+                        || !refresh.scopes.is_empty())
+                {
+                    diagnostics.push(ProfileValidationDiagnostic::error(
+                        source,
+                        profile_id,
+                        "credentials.refresh",
+                        "github_app_installation requires a token_url ending in /app/installations/{installation_id}/access_tokens and uses permissions material instead of scopes",
+                    ));
+                }
                 if refresh.strategy == ProviderCredentialRefreshStrategy::Unspecified {
                     diagnostics.push(ProfileValidationDiagnostic::error(
                         source,
@@ -5896,6 +5913,25 @@ binaries:
         );
     }
 
+    #[test]
+    fn github_app_profile_roundtrip_and_runtime_credentials() {
+        let profile = example_profile("github-app");
+        assert!(profile.required_static_credentials().is_empty());
+        assert!(validate_profile_set(&[("github-app.yaml".into(), profile.clone())]).is_empty());
+        let proto = profile.to_proto();
+        assert_eq!(
+            proto.credentials[0].refresh.as_ref().unwrap().strategy,
+            openshell_core::proto::ProviderCredentialRefreshStrategy::GithubAppInstallation as i32
+        );
+        let restored = ProviderTypeProfile::from_proto(&proto);
+        let yaml = serde_yml::to_string(&restored).unwrap();
+        assert!(yaml.contains("github_app_installation"));
+        let mut invalid = profile.clone();
+        invalid.credentials[0].refresh.as_mut().unwrap().token_url =
+            "https://api.github.com/token".into();
+        assert!(!validate_profile_set(&[("invalid.yaml".into(), invalid)]).is_empty());
+    }
+
     #[test]
     fn aws_sts_strategy_serde_roundtrip() {
         use openshell_core::proto::ProviderCredentialRefreshStrategy;