From 036e74a72f583d4a135558175f73a9d659002baa Mon Sep 17 00:00:00 2001
From: Marius Storhaug <marstor@hotmail.com>
Date: Wed, 6 Aug 2025 23:28:12 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=A9=B9=20[Patch]:=20Update=20the=20exampl?=
 =?UTF-8?q?es=20for=20how=20to=20connect=20using=20the=20module=20(#489)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Description

This pull request updates the `examples/Connecting.ps1` script to
clarify and expand the usage examples for GitHub connection methods,
including new authentication flows and improved documentation. The
changes also make some minor corrections to comments and example
commands related to context management.

Authentication and connection improvements:

* Added examples for connecting to GitHub programmatically using a token
and clarified support for both fine-grained and classic PATs in the
`Connect-GitHub` command.
* Added new examples for connecting using a GitHub App with a private
key stored in Azure Key Vault, including the use of `Connect-GitHubApp`
for organizational contexts.
* Improved comments for OAuth App, Device Flow, and PAT authentication
flows to clarify best practices and supported scenarios.

Context and profile management:

* Updated comments to clarify that context names can be tab-completed
and corrected a typo in the `Switch-GitHubContext` example
(`Switch-GitHubCwontext`).

## Type of change

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

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [x] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [ ] 🚀 [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

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 examples/Connecting.ps1 | 24 +++++++++++++++---------
 1 file changed, 15 insertions(+), 9 deletions(-)

diff --git a/examples/Connecting.ps1 b/examples/Connecting.ps1
index 810b6d05a..005786ce0 100644
--- a/examples/Connecting.ps1
+++ b/examples/Connecting.ps1
@@ -7,22 +7,30 @@ Connect-GitHub
 
 # Log on to a specific instance of GitHub (enterprise)
 Connect-GitHub -Host 'msx.ghe.com'
-Get-GitHubRepository -Context 'msx.ghe.com/MariusStorhaug' # Contexts should be selectable/overrideable on any call
+Get-GitHubRepository -Context 'msx.ghe.com/MariusStorhaug' # Contexts are selectable/overrideable on any call
 
-# Connect to GitHub interactively using OAuth App and Device Flow (should not use this, should we even support it?)
+# Connect to GitHub interactively using OAuth App and Device Flow.
 Connect-GitHub -Mode 'OAuthApp' -Scope 'gist read:org repo workflow'
 
-# Connect to GitHub interactively using less desired PAT flow
+# Connect to GitHub interactively using less desired PAT flow, supports both fine-grained and classic PATs
 Connect-GitHub -UseAccessToken
 
+# Connect to GitHub programatically (GitHub App Installation Access Token or PAT)
+Connect-GitHub -Token ***********
+
 # Connect to GitHub programatically (GitHub Actions)
 Connect-GitHub # Looks for the GITHUB_TOKEN variable
 
-# Connect to GitHub programatically (GitHub App, for GitHub Actions or external applications, JWT login)
+# Connect using a GitHub App and its private key (local signing of JWT)
 Connect-GitHub -ClientID '<client_id>' -PrivateKey '<private_key>'
 
-# Connect to GitHub programatically (GitHub App Installation Access Token or PAT)
-Connect-GitHub -Token ***********
+# Connect using a GitHub App and the Key vault for signing the JWT.
+# Prereq: The private key is stored in an Azure Key Vault and the shell has an authenticated Azure PowerShell or Azure CLI session
+$ClientID = 'Iv23lieHcDQDwVV3alK1'
+$KeyVaultKeyReference = 'https://psmodule-test-vault.vault.azure.net/keys/psmodule-ent-app'
+Connect-GitHub -ClientID $ClientID -KeyVaultKeyReference $KeyVaultKeyReference
+Connect-GitHubApp -Organization 'dnb-tooling'
+
 
 ###
 ### Contexts / Profiles
@@ -37,14 +45,12 @@ Get-GitHubContext -ListAvailable
 # Returns a specific context, autocomplete the name.
 Get-GitHubContext -Context 'msx.ghe.com/MariusStorhaug'
 
-# Take a name dynamically from Get-GitHubContext? Autocomplete the name
+# Take a name dynamically from Get-GitHubContext? tab-complete the name
 Switch-GitHubContext -Context 'msx.ghe.com/MariusStorhaug'
 
 # Set a specific context as the default context using pipeline
 'msx.ghe.com/MariusStorhaug' | Switch-GitHubContext
 
-Get-GitHubContext -Context 'github.com/MariusStorhaug' | Switch-GitHubContext
-
 # Abstraction layers on GitHubContexts
 Get-GitHubContext -Context 'msx.ghe.com/MariusStorhaug'