feat: add support for enterprise-level GitHub Apps (#263)

This pull request adds support for generating GitHub App installation
tokens for enterprise-level installations.

### What changed

- Added a new `enterprise` input to `action.yml`.
- Wired `enterprise` through `main.js` and `lib/main.js`.
- Added validation so `enterprise` cannot be combined with `owner` or
`repositories`.
- Implemented enterprise installation lookup using the direct GitHub API
route `GET /enterprises/{enterprise}/installation`, then used the
returned installation ID to mint an installation token through
`@octokit/auth-app`.
- Updated `README.md` with enterprise installation usage and input
documentation.
- Updated `dist/main.cjs` for the bundled action.
- Shared token creation retry behavior across repository, owner, and
enterprise paths so server errors and transient network errors are
retried, while client errors fail immediately.

### Tests

Added focused test coverage for:

- enterprise token creation
- enterprise token creation with explicit permissions
- enterprise installation not found
- mutual exclusivity with `owner`
- mutual exclusivity with `repositories`
- owner installation client errors are not retried
- transient network errors are retried during token creation

### Notes

- This keeps the existing repository-scoped token behavior unchanged.
- Owner, repository, and enterprise token creation now share the same
retry policy: server errors and recognized transient network errors are
retried, while client errors fail immediately. This intentionally fixes
the previous owner-path behavior that retried client errors.

Refs:
-
https://github.blog/changelog/2025-07-01-enterprise-level-access-for-github-apps-and-installation-automation-apis/
-
https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#get-an-enterprise-installation-for-the-authenticated-app

---------

Co-authored-by: Parker Brown <17183625+parkerbxyz@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 4 people

.gitignore

@@ -1,3 +1,4 @@
 .env
 coverage
 node_modules/
+.DS_Store

README.md

@@ -195,10 +195,32 @@ jobs:
           body: "Hello, World!"
 ```
 
+### Create a token for an enterprise installation
+
+```yaml
+on: [workflow_dispatch]
+
+jobs:
+  hello-world:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/create-github-app-token@v3
+        id: app-token
+        with:
+          client-id: ${{ vars.APP_CLIENT_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+          enterprise: my-enterprise-slug
+      - name: Call enterprise management REST API with gh
+        run: |
+          gh api /enterprises/my-enterprise-slug/apps/installable_organizations
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+```
+
 ### Create a token with specific permissions
 
 > [!NOTE]
-> Selected permissions must be granted to the installation of the specified app and repository owner. Setting a permission that the installation does not have will result in an error.
+> Selected permissions must be granted to the specified app installation. Setting a permission that the installation does not have will result in an error.
 
 ```yaml
 on: [issues]
@@ -356,6 +378,13 @@ steps:
 > [!NOTE]
 > If `owner` is set and `repositories` is empty, access will be scoped to all repositories in the provided repository owner's installation. If `owner` and `repositories` are empty, access will be scoped to only the current repository.
 
+### `enterprise`
+
+**Optional:** The slug of the enterprise account to generate a token for an enterprise installation.
+
+> [!NOTE]
+> The `enterprise` input is mutually exclusive with `owner` and `repositories`. Use it when the GitHub App is installed on an enterprise account. Enterprise installation tokens can call enterprise APIs, but do not grant organization or repository access.
+
 ### `permission-<permission name>`
 
 **Optional:** The permissions to grant to the token. By default, the token inherits all of the installation's permissions. We recommend to explicitly list the permissions that are required for a use case. This follows GitHub's own recommendation to [control permissions of `GITHUB_TOKEN` in workflows](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token). The documentation also lists all available permissions, just prefix the permission key with `permission-` (e.g., `pull-requests` → `permission-pull-requests`).
@@ -386,13 +415,14 @@ GitHub App slug.
 
 ## How it works
 
-The action creates an installation access token using [the `POST /app/installations/{installation_id}/access_tokens` endpoint](https://docs.github.com/rest/apps/apps?apiVersion=2022-11-28#create-an-installation-access-token-for-an-app). By default,
+The action creates an installation access token using [the `POST /app/installations/{installation_id}/access_tokens` endpoint](https://docs.github.com/rest/apps/apps?apiVersion=2022-11-28#create-an-installation-access-token-for-an-app).
+
+The token target depends on the inputs: `enterprise` creates a token for an enterprise installation, `owner` without `repositories` creates a token for all repositories in the owner's installation, `repositories` scopes the token to those repositories, and no target inputs scopes the token to the current repository.
 
-1. The token is scoped to the current repository or `repositories` if set.
-2. The token inherits all the installation's permissions.
-3. The token is set as output `token` which can be used in subsequent steps.
-4. Unless the `skip-token-revoke` input is set to true, the token is revoked in the `post` step of the action, which means it cannot be passed to another job.
-5. The token is masked, it cannot be logged accidentally.
+1. The token inherits all the installation's permissions.
+2. The token is set as output `token` which can be used in subsequent steps.
+3. Unless the `skip-token-revoke` input is set to true, the token is revoked in the `post` step of the action, which means it cannot be passed to another job.
+4. The token is masked, it cannot be logged accidentally.
 
 > [!NOTE]
 > Installation permissions can differ from the app's permissions they belong to. Installation permissions are set when an app is installed on an account. When the app adds more permissions after the installation, an account administrator will have to approve the new permissions before they are set on the installation.

action.yml

@@ -21,6 +21,9 @@ inputs:
   repositories:
     description: "Comma or newline-separated list of repositories to install the GitHub App on (defaults to current repository if owner is unset)"
     required: false
+  enterprise:
+    description: "The slug of the enterprise account where the GitHub App is installed (cannot be used with 'owner' or 'repositories')"
+    required: false
   skip-token-revoke:
     description: "If true, the token will not be revoked when the current job is complete"
     required: false

dist/main.cjs

@@ -22985,7 +22985,7 @@ function isNetworkError(error2) {
     return false;
   }
   const { message, stack } = error2;
-  if (message === "Load failed") {
+  if (message === "Load failed" || message.startsWith("Load failed (") && message.endsWith(")")) {
     return stack === void 0 || "__sentry_captured__" in error2;
   }
   if (message.startsWith("error sending request for url")) {
@@ -23196,104 +23196,133 @@ async function pRetry(input, options = {}) {
 }
 
 // lib/main.js
-async function main(clientId, privateKey, owner, repositories, permissions, core, createAppAuth2, request2, skipTokenRevoke) {
-  let parsedOwner = "";
-  let parsedRepositoryNames = [];
+async function main(clientId, privateKey, enterprise, owner, repositories, permissions, core, createAppAuth2, request2, skipTokenRevoke) {
+  if (enterprise && (owner || repositories.length > 0)) {
+    throw new Error("Cannot use 'enterprise' input with 'owner' or 'repositories' inputs");
+  }
+  const target = resolveInstallationTarget(enterprise, owner, repositories, core);
+  const auth5 = createAppAuth2({
+    appId: clientId,
+    privateKey,
+    request: request2
+  });
+  const { authentication, installationId, appSlug } = await pRetry(
+    () => getTokenFromTarget(request2, auth5, target, permissions),
+    createTokenRetryOptions(core, getTokenRetryDescription(target))
+  );
+  core.setSecret(authentication.token);
+  core.setOutput("token", authentication.token);
+  core.setOutput("installation-id", installationId);
+  core.setOutput("app-slug", appSlug);
+  if (!skipTokenRevoke) {
+    core.saveState("token", authentication.token);
+    core.saveState("expiresAt", authentication.expiresAt);
+  }
+}
+function resolveInstallationTarget(enterprise, owner, repositories, core) {
+  if (enterprise) {
+    core.info(`Creating enterprise installation token for enterprise "${enterprise}".`);
+    return { type: "enterprise", enterprise };
+  }
   if (!owner && repositories.length === 0) {
-    const [owner2, repo] = String(process.env.GITHUB_REPOSITORY).split("/");
-    parsedOwner = owner2;
-    parsedRepositoryNames = [repo];
+    const [defaultOwner, repo] = String(process.env.GITHUB_REPOSITORY).split("/");
     core.info(
-      `Inputs 'owner' and 'repositories' are not set. Creating token for this repository (${owner2}/${repo}).`
+      `Inputs 'owner' and 'repositories' are not set. Creating token for this repository (${defaultOwner}/${repo}).`
     );
+    return {
+      type: "repository",
+      owner: defaultOwner,
+      repositories: [repo]
+    };
   }
   if (owner && repositories.length === 0) {
-    parsedOwner = owner;
     core.info(
       `Input 'repositories' is not set. Creating token for all repositories owned by ${owner}.`
     );
+    return { type: "owner", owner };
   }
-  if (!owner && repositories.length > 0) {
-    parsedOwner = String(process.env.GITHUB_REPOSITORY_OWNER);
-    parsedRepositoryNames = repositories;
+  const parsedOwner = owner || String(process.env.GITHUB_REPOSITORY_OWNER);
+  if (!owner) {
     core.info(
       `No 'owner' input provided. Using default owner '${parsedOwner}' to create token for the following repositories:${repositories.map((repo) => `
 - ${parsedOwner}/${repo}`).join("")}`
     );
-  }
-  if (owner && repositories.length > 0) {
-    parsedOwner = owner;
-    parsedRepositoryNames = repositories;
+  } else {
     core.info(
-      `Inputs 'owner' and 'repositories' are set. Creating token for the following repositories:
-      ${repositories.map((repo) => `
+      `Inputs 'owner' and 'repositories' are set. Creating token for the following repositories:${repositories.map((repo) => `
 - ${parsedOwner}/${repo}`).join("")}`
     );
   }
-  const auth5 = createAppAuth2({
-    appId: clientId,
-    privateKey,
-    request: request2
-  });
-  let authentication, installationId, appSlug;
-  if (parsedRepositoryNames.length > 0) {
-    ({ authentication, installationId, appSlug } = await pRetry(
-      () => getTokenFromRepository(
+  return {
+    type: "repository",
+    owner: parsedOwner,
+    repositories
+  };
+}
+function getTokenRetryDescription(target) {
+  switch (target.type) {
+    case "enterprise":
+      return `enterprise "${target.enterprise}"`;
+    case "repository":
+      return `"${target.repositories.map((repository) => `${target.owner}/${repository}`).join(",")}"`;
+    case "owner":
+      return `"${target.owner}"`;
+    /* c8 ignore next 2 */
+    default:
+      throw new Error(`Unsupported installation target type: ${target.type}`);
+  }
+}
+function getTokenFromTarget(request2, auth5, target, permissions) {
+  switch (target.type) {
+    case "enterprise":
+      return getTokenFromEnterprise(request2, auth5, target.enterprise, permissions);
+    case "repository":
+      return getTokenFromRepository(
         request2,
         auth5,
-        parsedOwner,
-        parsedRepositoryNames,
+        target.owner,
+        target.repositories,
         permissions
-      ),
-      {
-        shouldRetry: ({ error: error2 }) => error2.status >= 500,
-        onFailedAttempt: (context) => {
-          core.info(
-            `Failed to create token for "${parsedRepositoryNames.join(
-              ","
-            )}" (attempt ${context.attemptNumber}): ${context.error.message}`
-          );
-        },
-        retries: 3
-      }
-    ));
-  } else {
-    ({ authentication, installationId, appSlug } = await pRetry(
-      () => getTokenFromOwner(request2, auth5, parsedOwner, permissions),
-      {
-        onFailedAttempt: (context) => {
-          core.info(
-            `Failed to create token for "${parsedOwner}" (attempt ${context.attemptNumber}): ${context.error.message}`
-          );
-        },
-        retries: 3
-      }
-    ));
-  }
-  core.setSecret(authentication.token);
-  core.setOutput("token", authentication.token);
-  core.setOutput("installation-id", installationId);
-  core.setOutput("app-slug", appSlug);
-  if (!skipTokenRevoke) {
-    core.saveState("token", authentication.token);
-    core.saveState("expiresAt", authentication.expiresAt);
+      );
+    case "owner":
+      return getTokenFromOwner(request2, auth5, target.owner, permissions);
+    /* c8 ignore next 2 */
+    default:
+      throw new Error(`Unsupported installation target type: ${target.type}`);
   }
 }
+function createTokenRetryOptions(core, targetDescription) {
+  return {
+    shouldRetry: ({ error: error2 }) => error2.status >= 500 || isNetworkError(error2),
+    onFailedAttempt: (context) => {
+      core.info(
+        `Failed to create token for ${targetDescription} (attempt ${context.attemptNumber}): ${context.error.message}`
+      );
+    },
+    retries: 3
+  };
+}
+async function createInstallationAuthResult(auth5, installation, permissions, options = {}) {
+  const authentication = await auth5({
+    type: "installation",
+    installationId: installation.id,
+    permissions,
+    ...options
+  });
+  return {
+    authentication,
+    installationId: installation.id,
+    appSlug: installation["app_slug"]
+  };
+}
 async function getTokenFromOwner(request2, auth5, parsedOwner, permissions) {
   const response = await request2("GET /users/{username}/installation", {
     username: parsedOwner,
     request: {
       hook: auth5.hook
     }
   });
-  const authentication = await auth5({
-    type: "installation",
-    installationId: response.data.id,
-    permissions
-  });
-  const installationId = response.data.id;
-  const appSlug = response.data["app_slug"];
-  return { authentication, installationId, appSlug };
+  return createInstallationAuthResult(auth5, response.data, permissions);
 }
 async function getTokenFromRepository(request2, auth5, parsedOwner, parsedRepositoryNames, permissions) {
   const response = await request2("GET /repos/{owner}/{repo}/installation", {
@@ -23303,15 +23332,28 @@ async function getTokenFromRepository(request2, auth5, parsedOwner, parsedReposi
       hook: auth5.hook
     }
   });
-  const authentication = await auth5({
-    type: "installation",
-    installationId: response.data.id,
-    repositoryNames: parsedRepositoryNames,
-    permissions
+  return createInstallationAuthResult(auth5, response.data, permissions, {
+    repositoryNames: parsedRepositoryNames
   });
-  const installationId = response.data.id;
-  const appSlug = response.data["app_slug"];
-  return { authentication, installationId, appSlug };
+}
+async function getTokenFromEnterprise(request2, auth5, enterprise, permissions) {
+  let response;
+  try {
+    response = await request2("GET /enterprises/{enterprise}/installation", {
+      enterprise,
+      request: {
+        hook: auth5.hook
+      }
+    });
+  } catch (error2) {
+    if (error2.status === 404) {
+      throw new Error(
+        `No enterprise installation found matching the enterprise slug "${enterprise}".`
+      );
+    }
+    throw error2;
+  }
+  return createInstallationAuthResult(auth5, response.data, permissions);
 }
 
 // lib/request.js
@@ -23355,13 +23397,15 @@ async function run() {
     throw new Error("The 'client-id' (or deprecated 'app-id') input must be set to a non-empty string. If using a secret or variable, ensure it is available in this workflow context.");
   }
   const privateKey = getInput("private-key");
+  const enterprise = getInput("enterprise");
   const owner = getInput("owner");
   const repositories = getInput("repositories").split(/[\n,]+/).map((s) => s.trim()).filter((x) => x !== "");
   const skipTokenRevoke = getBooleanInput("skip-token-revoke");
   const permissions = getPermissionsFromInputs(process.env);
   return main(
     clientId,
     privateKey,
+    enterprise,
     owner,
     repositories,
     permissions,