🚀 [Feature]: Add ability to log on with GitHub App (#9)

## Description

- Add ability to log on with GitHub App using `ClientID` and
`PrivateKey`.

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [ ] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [x] 🚀 [Feature]
- [ ] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

Author: MariusStorhaug

.github/workflows/Action-Test.yml

@@ -40,12 +40,16 @@ jobs:
         uses: ./
         with:
           Script: |
-            LogGroup "My group" {
-              "This is a group"
+            LogGroup 'Get-GitHubContext' {
+              Get-GitHubContext
             }
 
-  ActionTestWithVersion:
-    name: Action-Test - [WithVersion]
+            LogGroup 'Get-GitHubZen' {
+              Get-GitHubZen
+            }
+
+  ActionTestWithoutToken:
+    name: Action-Test - [WithoutToken]
     runs-on: ubuntu-latest
     steps:
       # Need to check out as part of the test, as its a local action
@@ -55,45 +59,59 @@ jobs:
       - name: Action-Test
         uses: ./
         with:
-          Verbose: true
-          Version: 0.8.4
+          Token: ''
           Script: |
-            LogGroup "Get-GitHubZen" {
-              Get-GitHubZen
+            LogGroup 'Get-GitHubContext' {
+              Get-GitHubContext
             }
 
-            LogGroup "Get-GitHubOctocat" {
-              Get-GitHubOctocat
+            LogGroup 'My group' {
+              'This is a group'
             }
 
-  ActionTestConsecutive:
-    name: Action-Test - [Consecutive]
+  ActionTestWithPAT:
+    name: Action-Test - [WithPAT]
     runs-on: ubuntu-latest
     steps:
       # Need to check out as part of the test, as its a local action
       - name: Checkout repo
         uses: actions/checkout@v4
 
-      - name: Action-Test 1
+      - name: Action-Test
         uses: ./
         with:
+          Token: ${{ secrets.TEST_PAT }}
           Script: |
-            LogGroup "Get-GitHubZen" {
-              Get-GitHubZen
+            LogGroup 'Get-GitHubContext' {
+              Get-GitHubContext
             }
 
-      - name: Action-Test 2
-        uses: ./
-        with:
-          Script: |
-            LogGroup "Get-GitHubOctocat" {
-              Get-GitHubOctocat
+            LogGroup 'Get-GitHubUser' {
+              Get-GitHubUser
             }
 
-      - name: Action-Test 3
+  ActionTestWithGitHubApp:
+    name: Action-Test - [GitHubApp]
+    runs-on: ubuntu-latest
+    steps:
+      # Need to check out as part of the test, as its a local action
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Action-Test
         uses: ./
         with:
+          ClientID: ${{ secrets.TEST_APP_CLIENT_ID }}
+          PrivateKey: ${{ secrets.TEST_APP_PRIVATE_KEY }}
           Script: |
-            LogGroup "Get-GitHubRateLimit" {
-              Get-GitHubRateLimit
+            LogGroup 'Get-GitHubContext' {
+              Get-GitHubContext
+            }
+
+            LogGroup 'Get-GitHubApp' {
+              Get-GitHubApp
+            }
+
+            LogGroup 'Get-GitHubAppInstallation' {
+              Get-GitHubAppInstallation
             }

README.md

@@ -11,7 +11,9 @@ For more information on the available functions and automatic loaded variables,
 | Name | Description | Required | Default |
 | - | - | - | - |
 | `Script` | The script to run | false | |
-| `Token` | The GitHub token to use. This will override the default behavior of using the `GITHUB_TOKEN` environment variable. | false | `${{ github.token }}` |
+| `Token` | Log in using an Installation Access Token (IAT) | false | `${{ github.token }}` |
+| `ClientID` | Log in using a GitHub App, using the App's Client ID and Private Key | false | |
+| `PrivateKey` | Log in using a GitHub App, using the App's Client ID and Private Key | false | |
 | `Debug` | Enable debug output | false | `'false'` |
 | `Verbose` | Enable verbose output | false | `'false'` |
 | `Version` | Specifies the version of the GitHub module to be installed. The value must be an exact version. | false | |
@@ -20,7 +22,26 @@ For more information on the available functions and automatic loaded variables,
 
 ### Examples
 
-#### Example 1: Run a script that uses the GitHub PowerShell module
+#### Example 1: Run a GitHub PowerShell script
+
+Run a script that uses the GitHub PowerShell module.
+This example runs an authenticated script using the `GITHUB_TOKEN` and gets the GitHub Zen message.
+
+```yaml
+jobs:
+  Run-Script:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run script
+        uses: PSModule/GitHub-Script@v1
+        with:
+          Script: |
+            LogGroup "Get-GitHubZen" {
+              Get-GitHubZen
+            }
+```
+
+#### Example 2: Run a GitHub PowerShell script without a token
 
 Run a script that uses the GitHub PowerShell module.
 This example runs a non-authenticated script that gets the GitHub Zen message.
@@ -33,16 +54,17 @@ jobs:
       - name: Run script
         uses: PSModule/GitHub-Script@v1
         with:
+          Token: ''
           Script: |
             LogGroup "Get-GitHubZen" {
               Get-GitHubZen
             }
 ```
 
-#### Example 2: Run a script that uses the GitHub PowerShell module with a token
+#### Example 3: Run a GitHub PowerShell script with a custom token
 
-Run a script that uses the GitHub PowerShell module with a token.
-This example runs an authenticated script that gets the GitHub Zen message.
+Run a script that uses the GitHub PowerShell module with a token. The token can be both a personal access token (PAT) or
+an installation access token (IAT). This example runs an authenticated script that gets the GitHub Zen message.
 
 ```yaml
 jobs:
@@ -52,13 +74,34 @@ jobs:
       - name: Run script
         uses: PSModule/GitHub-Script@v1
         with:
-          Token: ${{ github.token }}
+          Token: ${{ secrets.Token }}
           Script: |
             LogGroup "Get-GitHubZen" {
               Get-GitHubZen
             }
 ```
 
+#### Example 4: Run a GitHub PowerShell script with a GitHub App using a Client ID and Private Key
+
+Run a script that uses the GitHub PowerShell module with a GitHub App.
+This example runs an authenticated script that gets the GitHub App.
+
+```yaml
+jobs:
+  Run-Script:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run script
+        uses: PSModule/GitHub-Script@v1
+        with:
+          ClientID: ${{ secrets.CLIENT_ID }}
+          PrivateKey: ${{ secrets.PRIVATE_KEY }}
+          Script: |
+            LogGroup "Get-GitHubApp" {
+              Get-GitHubApp
+            }
+```
+
 ## Related projects
 
 - [actions/create-github-app-token](https://github.com/actions/create-github-app-token) -> Functionality will be brought into GitHub PowerShell module.

action.yml

@@ -10,9 +10,15 @@ inputs:
     description: The script to run.
     required: false
   Token:
-    description: The access token to use.
+    description: Log in using an Installation Access Token (IAT).
     required: false
     default: ${{ github.token }}
+  ClientID:
+    description: Log in using a GitHub App, using the App's Client ID and Private Key.
+    required: false
+  PrivateKey:
+    description: Log in using a GitHub App, using the App's Client ID and Private Key.
+    required: false
   Debug:
     description: Enable debug output.
     required: false
@@ -41,6 +47,8 @@ runs:
       working-directory: ${{ inputs.WorkingDirectory }}
       env:
         GITHUB_ACTION_INPUT_Token: ${{ inputs.Token }}
+        GITHUB_ACTION_INPUT_ClientID: ${{ inputs.ClientID }}
+        GITHUB_ACTION_INPUT_PrivateKey: ${{ inputs.PrivateKey }}
         GITHUB_ACTION_INPUT_Debug: ${{ inputs.Debug }}
         GITHUB_ACTION_INPUT_Verbose: ${{ inputs.Verbose }}
         GITHUB_ACTION_INPUT_Version: ${{ inputs.Version }}

scripts/main.ps1

@@ -48,15 +48,20 @@ if (-not $alreadyImported) {
 }
 '::endgroup::'
 
-LogGroup 'Connect-Github' {
-    if (-not [string]::IsNullOrEmpty($env:GITHUB_ACTION_INPUT_Token)) {
-        Write-Verbose "Setting GITHUB_TOKEN to provided input 'Token'"
-        Connect-Github -Token $env:GITHUB_ACTION_INPUT_Token
-    } elseif (-not [string]::IsNullOrEmpty($env:GITHUB_ACTION_INPUT_ClientID) -and -not [string]::IsNullOrEmpty($env:GITHUB_ACTION_INPUT_PrivateKey)) {
-        Write-Verbose "Setting ClientID and PEM to provided inputs 'ClientID' and 'PEM'"
+$providedToken = -not [string]::IsNullOrEmpty($env:GITHUB_ACTION_INPUT_Token)
+$providedClientID = -not [string]::IsNullOrEmpty($env:GITHUB_ACTION_INPUT_ClientID)
+$providedPrivateKey = -not [string]::IsNullOrEmpty($env:GITHUB_ACTION_INPUT_PrivateKey)
+Write-Verbose "Provided authentication info:"
+Write-Verbose "Token:      [$providedToken]"
+Write-Verbose "ClientID:   [$providedClientID]"
+Write-Verbose "PrivateKey: [$providedPrivateKey]"
+
+if ($providedClientID -and $providedPrivateKey) {
+    LogGroup 'Connect-Github - GitHub App' {
         Connect-Github -ClientID $env:GITHUB_ACTION_INPUT_ClientID -PrivateKey $env:GITHUB_ACTION_INPUT_PrivateKey
-    } elseif (-not [string]::IsNullOrEmpty($env:GITHUB_ACTION_INPUT_JWT)) {
-        Write-Verbose "Setting JWT to provided input 'JWT'"
-        Connect-Github -JWT $env:GITHUB_ACTION_INPUT_JWT
+    }
+} elseif ($providedToken) {
+    LogGroup 'Connect-Github - Token' {
+        Connect-Github -Token $env:GITHUB_ACTION_INPUT_Token
     }
 }