From 0735d7910f37690a85af436f06afded391ee600a Mon Sep 17 00:00:00 2001
From: "Michael B. Gale" <mbg@github.com>
Date: Tue, 13 Oct 2026 14:24:12 +0100
Subject: [PATCH] Improve `GitHubApiDetails` types and documentation

---
 src/api-client.ts | 32 +++++++++++++++++++++++++-------
 1 file changed, 25 insertions(+), 7 deletions(-)

diff --git a/src/api-client.ts b/src/api-client.ts
index 6a5e99468..80872c31e 100644
--- a/src/api-client.ts
+++ b/src/api-client.ts
@@ -43,20 +43,38 @@ const GITHUB_ENTERPRISE_VERSION_HEADER = "x-github-enterprise-version";
  */
 export const DO_NOT_RETRY_STATUSES = [400, 410, 422, 451];
 
+/**
+ * Represents information about a GitHub instance, how to authenticate to it,
+ * and how to authenticate to other repos on it.
+ */
 export type GitHubApiCombinedDetails = GitHubApiDetails &
   GitHubApiExternalRepoDetails;
 
-export interface GitHubApiDetails {
-  auth: string;
+/** Represents information about a GitHub instance. */
+export type GitHubInstance = {
+  /** The base URL of the GitHub instance, such as `https://github.com`. */
   url: string;
+  /**
+   * The API base URL of the GitHub instance, such as `https://api.github.com`.
+   * Typically this is the `api.` subdomain of the `url` domain.
+   */
   apiURL: string | undefined;
-}
+};
 
-export interface GitHubApiExternalRepoDetails {
+/** Represents a {@link GitHubInstance} with a token for accessing the API. */
+export type GitHubApiDetails = GitHubInstance & {
+  /** The token to use for accessing the API of the GitHub instance. */
+  auth: string;
+};
+
+/**
+ * Represents information for accessing a repository on the same GitHub instance as the Action
+ * is currently running on.
+ */
+export type GitHubApiExternalRepoDetails = {
+  /** An optional token for accessing repo(s) on the same GitHub instance. */
   externalRepoAuth?: string;
-  url: string;
-  apiURL: string | undefined;
-}
+};
 
 /**
  * Gets the configuration for the private registry authentication proxy,