Add support for enterprise installation tokens (#10)

* Add support for GitHub App enterprise installations

If accountType is enterprise (owner is mandatory ands should be filled with the enterprise slug) returns an installation id for the app installed at the enterprise level so calls can be made at enterprise level.

- Bump axios
- Bump extension and task version

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: Tiago Pascoal <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

.gitignore

@@ -8,6 +8,7 @@ lib
 .taskkey
 
 coverage/
+smoke-tests/
 
 # Test results
-test-results/
+test-results/

README.md

@@ -8,18 +8,18 @@ Azure Pipelines extension to create a GitHub App installation tokens that can be
 ## Features
 
 - Generates GitHub App installation tokens for API authentication
-- Supports organization-wide or repository-specific tokens
+- Supports organization-wide, user-level, or enterprise-level tokens
 - Provides multiple authentication options (service connection or direct inputs)
 - Handles proxy configurations through environment variables
 - Secure handling of private keys and credentials
 - Cross-platform compatibility
 
 ## Prerequisites
 
-1. A GitHub App created and installed in your organization
+1. A GitHub App created and installed in your organization, user account, or enterprise
 2. The GitHub App's private key (PEM format)
 3. The GitHub App client ID
-4. The GitHub App must be installed in the organization where you want to generate tokens
+4. The GitHub App must be installed in the organization, user account, or enterprise where you want to generate tokens
 
 ## Configuration
 
@@ -64,9 +64,9 @@ steps:
 | Parameter | Required | Description |
 |-----------|----------|-------------|
 | githubAppConnection | No | The GitHub App connection to use (preferred method) |
-| owner | No | The GitHub organization name or user account where the app is installed. If not provided, it will be automatically fetched from the `Build.Repository.Name` variable. |
-| accountType | No | The type of account to use for the token. Options: `org` (organization) or `user` (user account). Default is `org`. |
-| repositories | No | Comma-separated list of repositories to scope the token to. If empty, token will be scoped to all repositories (in which the app has access to) |
+| owner | No | The GitHub organization name, user account, or enterprise slug where the app is installed. **Required for enterprise account type.** If not provided (for org/user), it will be automatically fetched from the `Build.Repository.Name` variable. |
+| accountType | No | The type of account to use for the token. Options: `org` (organization), `user` (user account), or `enterprise` (enterprise account). Default is `org`. |
+| repositories | No | Comma-separated list of repositories to scope the token to. If empty, token will be scoped to all repositories (in which the app has access to). **Not allowed for enterprise account type.** |
 | appClientId | No* | The GitHub App ID (required if not using service connection) |
 | certificate | No* | The PEM certificate content (required if not using service connection) |
 | certificateFile | No | Alternative to certificate - filename containing the PEM content |
@@ -189,6 +189,41 @@ steps:
     permissions: '{"contents":"read","pulls":"write","issues":"write"}'  # Restricts token permissions
 ```
 
+### Enterprise Installation Token
+
+For GitHub Apps installed at the enterprise level:
+
+```yaml
+steps:
+- task: create-github-app-token@1
+  name: enterpriseToken
+  inputs:
+    githubAppConnection: 'MyGitHubAppConnection'
+    accountType: 'enterprise'
+    owner: 'my-enterprise'  # Enterprise slug/name (required for enterprise)
+- bash: |
+    gh api \
+    --method GET -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" \
+    /enterprises/my-enterprise
+  displayName: 'Access enterprise using GitHub CLI'
+  env:
+    GH_TOKEN: $(enterpriseToken.installationToken)
+```
+
+### Enterprise with Direct Certificate Input
+
+```yaml
+steps:
+- task: create-github-app-token@1
+  inputs:
+    accountType: 'enterprise'
+    owner: 'my-enterprise'  # Required for enterprise account type
+    appClientId: 'lv2313qqwqeqweqw'
+    certificate: '$(githubAppPem)'
+    # Note: repositories input not allowed for enterprise account type
+    # Note: forceRepoScope not allowed for enterprise account type
+```
+
 ## Proxy Support
 
 The task automatically detects and uses proxy settings from the following environment variables:
@@ -210,6 +245,30 @@ Common issues and solutions:
    - If you are trying to request `admin:read` permission, the app needs to have `admin:read` or `admin:org` in the GitHub App configuration
    - The token can only have equal or lower permissions than what is configured in the GitHub App settings
 
+### Enterprise-Specific Issues
+
+5. **Enterprise installation not found**: 
+   - Verify the GitHub App is installed at the enterprise level (not just organization level)
+   - Ensure the `owner` parameter contains the correct enterprise slug/name
+   - Check that the GitHub App has permissions to access enterprise resources
+6. **Multiple enterprise installations found**: If you have access to multiple enterprises, specify the exact enterprise slug in the `owner` parameter
+7. **Enterprise account type restrictions**:
+   - Cannot use `repositories` parameter with enterprise account type (tokens are enterprise-scoped)
+   - Cannot use `forceRepoScope` in service connections with enterprise account type
+   - The `owner` parameter is mandatory for enterprise account type
+8. **Rate limiting during installation lookup**: Enterprise installations use pagination which may hit rate limits with many installations. The task automatically handles rate limiting by waiting if the reset time is within 5 minutes.
+
+### Account Type Differences
+
+| Feature | Organization | User | Enterprise |
+|---------|-------------|------|------------|
+| Repository scoping | ✅ Supported | ✅ Supported | ❌ Not supported |
+| forceRepoScope | ✅ Supported | ✅ Supported | ❌ Not supported |
+| Owner parameter | Optional* | Optional* | **Required** |
+| Direct API lookup | ✅ Yes | ✅ Yes | ❌ Uses pagination workaround |
+
+*Owner is optional for org/user if using GitHub repository provider (auto-extracted from Build.Repository.Name)
+
 > [!TIP]
 > If you expand the task logs, you can see extra info like the token permissions and repo access. (If you run the pipeline in debug mode it will have extra info as well).
 

create-github-app-token/package-lock.json

@@ -14,7 +14,7 @@
   "license": "ISC",
   "description": "",
   "dependencies": {
-    "axios": "^1.6.2",
+    "axios": "^1.11.0",
     "azure-pipelines-task-lib": "^5.0.0",
     "http-proxy-agent": "^5.0.0",
     "https-proxy-agent": "^5.0.0",

create-github-app-token/package.json

@@ -35,10 +35,10 @@ export class GitHubService {
     }
 
     async generateJWT(appIdOrClientId: string, privateKey: string): Promise<string> {
-        const now = Math.floor(Date.now() / 1000);
+        const nowSeconds = Math.floor(Date.now() / 1000);
         const payload = {
-            iat: now - 60,        // issued at time, 60s in the past to allow for clock drift
-            exp: now + constants.JWT_EXPIRATION,
+            iat: nowSeconds - constants.JWT_CLOCK_DRIFT_SECONDS,        // issued at time, 60s in the past to allow for clock drift
+            exp: nowSeconds + constants.JWT_EXPIRATION - constants.JWT_CLOCK_DRIFT_SECONDS, // expiration time, 10 minutes from now
             iss: appIdOrClientId  // GitHub App's client (preferable) or app identifier
         };
 
@@ -53,16 +53,17 @@ export class GitHubService {
      * - https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#get-a-user-installation-for-the-authenticated-app
      * - https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#get-an-organization-installation-for-the-authenticated-app
      * - https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#get-a-repository-installation-for-the-authenticated-app
+     * - https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#list-installations-for-the-authenticated-app (for enterprise installations)
      * 
      * @param jwtToken - The JSON Web Token (JWT) used for authentication with the GitHub API.
-     * @param owner - The owner of the repository or organization (username or organization name).
-     * @param isOrg - A boolean indicating whether the owner is an organization (not relevant if repo is being passed).
+     * @param owner - The owner of the repository, organization, or enterprise (username, organization name, or enterprise slug).
+     * @param accountType - The type of account: 'org', 'user', or 'enterprise'.
      * @param repositories - An optional array of repository names to narrow down the installation ID retrieval.
      *                        If provided, the first repository in the array will be used to get the installation token.
      * @returns A promise that resolves to the installation ID of the GitHub App.
      * @throws An error if the repository name is invalid or if the API request fails.
      */
-    async getInstallationId(jwtToken: string, owner: string, isOrg: boolean, repositories: string[] = []): Promise<number> {
+    async getInstallationId(jwtToken: string, appClientId: string, owner: string, accountType: string, repositories: string[] = []): Promise<number> {
         let url = undefined
         let groupName = '';
         let id = 0;
@@ -77,7 +78,10 @@ export class GitHubService {
                 if (!validateRepositoryName(repo)) {
                     throw new Error(`Invalid repository name format: ${repo}. It can only contain ASCII letters, digits, and the characters ., -, and _`);
                 }
-            } else if (isOrg) {
+            } else if (accountType.toLowerCase() === constants.ACCOUNT_TYPE_ENTERPRISE) {
+                // Enterprise installations require pagination through all installations
+                return await this.getEnterpriseInstallationId(jwtToken, appClientId);
+            } else if (accountType.toLowerCase() === constants.ACCOUNT_TYPE_ORG) {
                 groupName = `##[group]Get Installation ID for organization ${owner}`;
                 url = `${this.baseUrl}/orgs/${owner}/installation`;
             } else {
@@ -113,9 +117,17 @@ export class GitHubService {
             tl.debug(`Target type: ${response.data.target_type}`);
 
         } catch (err: any) {
+
+            this.dumpHeaders(err.response?.headers);
+
             let message = '';
             if (err.status === 404) {
-                const targetType = isOrg ? 'Organization' : 'account';
+                let targetType = 'account';
+                if (accountType.toLowerCase() === constants.ACCOUNT_TYPE_ORG) {
+                    targetType = 'Organization';
+                } else if (accountType.toLowerCase() === constants.ACCOUNT_TYPE_ENTERPRISE) {
+                    targetType = 'Enterprise';
+                }
                 message = `GitHub App not found for ${targetType} ${owner}. Please verify the installation${repositories.length ? ' and repository access' : ''}.`;
             } else {
                 message = `Failed to get installation ID: ${err.message}`;
@@ -127,6 +139,114 @@ export class GitHubService {
         return id;
     }
 
+    /**
+     * Gets the installation ID for an enterprise installation by listing all installations
+     * and filtering for enterprise type. Handles pagination automatically.
+     * 
+     * Note: This is a workaround since there is no direct API to get the installation ID 
+     * for enterprise installations (unlike organizations and repositories).
+     * 
+     * API: https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#list-installations-for-the-authenticated-app
+     * 
+     * @param jwtToken - The JWT token for authentication
+     * @param appIdOrClientId - GitHub App ID or Client ID to match against
+     * @returns Promise<number> - The installation ID
+     * @throws Error if no matching app installation found for enterprises, or API errors
+     */
+    async getEnterpriseInstallationId(jwtToken: string, appIdOrClientId: string): Promise<number> {
+        const groupName = `##[group]Get Installation ID for enterprise app ${appIdOrClientId}`;
+        console.log(`##[group]${groupName}`);
+        console.log('Searching for enterprise installation across all app installations (workaround - no direct API available)');
+
+        let page = 1;
+        const perPage = 100; // Maximum allowed by GitHub API
+        
+        try {
+            while (true) {
+                const url = `${this.baseUrl}/app/installations?per_page=${perPage}&page=${page}`;
+                tl.debug(`Installation list request URL: ${url} (page ${page})`);
+
+                const response = await this.client.get(url, {
+                    headers: {
+                        'Authorization': `Bearer ${jwtToken}`
+                    }
+                });
+
+                this.dumpHeaders(response.headers);
+                tl.debug(`Response payload (page ${page}): ${JSON.stringify(response.data)}`);
+
+                const installations = response.data;
+                tl.debug(`Processing page ${page} of installations (${installations.length} installations)`);
+
+                // Find matching installation by app ID or app client ID
+                const matchingInstallation = installations.find((installation: any) => 
+                    installation.target_type === 'Enterprise' &&
+                    ( 
+                        installation.app_id?.toString() === appIdOrClientId ||
+                        installation.client_id === appIdOrClientId
+                    )
+                );
+
+                if (matchingInstallation) {
+                    console.log(`Found enterprise installation for app ID/client ID '${appIdOrClientId}' on page ${page}`);
+                    const installationId = matchingInstallation.id;
+
+                    tl.debug(`Enterprise installation found: ${matchingInstallation.account.name} (install ID: ${installationId})`);
+                    tl.debug(`Installation app slug: ${matchingInstallation.app_slug || 'N/A'}`);
+                    tl.debug(`Installation app name: ${matchingInstallation.app_name || 'N/A'}`);
+                    
+                    return installationId;
+                }
+
+                // Check if we've reached the end of results using GitHub's pagination headers
+                const linkHeader = response.headers['link'];
+                if (!linkHeader || !linkHeader.includes('rel="next"')) {
+                    console.log(`No 'next' link header found. Reached end of installations (page ${page}).`);
+                    break;
+                }
+
+                // Check rate limiting and wait if necessary
+                const rateLimitRemaining = parseInt(response.headers['x-ratelimit-remaining'] || '0');
+                const rateLimitReset = parseInt(response.headers['x-ratelimit-reset'] || '0');
+                const currentTime = Math.floor(Date.now() / 1000);
+                
+                if (rateLimitRemaining === 0 && (rateLimitReset - currentTime) <= 300) {
+                    const waitTime = (rateLimitReset - currentTime) + 10; // Add 10 seconds buffer
+                    console.log(`Rate limit approaching. Waiting ${waitTime} seconds before next request.`);
+                    await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
+                } else if (rateLimitRemaining === 0) {
+                    const resetTime = new Date(rateLimitReset * 1000).toISOString();
+                    throw new Error(`GitHub API rate limit exceeded. Reset time: ${resetTime}. Please try again later.`);
+                }
+
+                page++;
+            }
+
+            // If we reach here, the enterprise installation was not found
+            throw new Error(`GitHub App installation not found for app ID/client ID '${appIdOrClientId}'. Please verify the app ID/client ID and enterprise installation.`);
+
+        } catch (err: any) {
+            let message = '';
+            if (err.response && err.response.status === 401) {
+                message = `GitHub App JWT authentication failed. Please verify the app credentials.`;
+            } else if (err.response && err.response.status === 403) {
+                message = `GitHub App does not have permission to list installations. Please verify the app permissions.`;
+            } else if (err.message.includes('rate limit') || err.message.includes('Rate limit')) {
+                throw err; // Re-throw rate limit errors as-is
+            } else {
+                message = err.message || `Failed to get enterprise installation ID: ${err}`;
+            }
+            
+            if (message !== err.message) {
+                throw new Error(message);
+            } else {
+                throw err;
+            }
+        } finally {
+            console.log('##[endgroup]')
+        }
+    }
+
     /**
      * Generates an installation token for a GitHub App installation.
      * 
@@ -240,11 +360,12 @@ export class GitHubService {
      * @param headers - An object containing the headers to be logged, where each key is the header name
      * and the corresponding value is the header value.
      */
-    private dumpHeaders(headers: any) {
-        Object.keys(headers).forEach((key) => {
-            const value = headers[key];
+    private dumpHeaders(headers: Record<string, any> | undefined | null): void {
+        if (!headers || tl.getVariable('System.Debug')?.toLowerCase() !== 'true') return;
+        
+        for (const [key, value] of Object.entries(headers)) {
             tl.debug(`Header: ${key} = ${value}`);
-        });
+        }
     }
 
     private formatPermissions(permissions: any): string {