From 04288fb100012387ecbbb5281efa79386083f634 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Mon, 6 Jul 2026 08:26:54 +0200 Subject: [PATCH 1/6] Standardize README landing page --- README.md | 234 +++--------------------------------------------------- 1 file changed, 12 insertions(+), 222 deletions(-) diff --git a/README.md b/README.md index c84fbb0f4..3382bb9a0 100644 --- a/README.md +++ b/README.md @@ -1,237 +1,27 @@ -# GitHub PowerShell +# GitHub -The module provides a PowerShell-flavored approach to managing and automating your GitHub environments. It's tailored for developers, administrators, -and GitHub enthusiasts who want to use PowerShell to integrate or manage GitHub seamlessly. +GitHub is a PowerShell module for interacting with GitHub, both interactively and in automation. -## Supported use-cases +## Installation -- **Operate any GitHub environment** - As an operator of any type of GitHub environment, you can use this module to automate your workflows and tasks. The module supports connecting - with multiple accounts; be that GitHub (public, github.com), GitHub Enterprise Cloud (GHEC, including GHE.com) and GitHub Enterprise Server (GHES). -- **A great GitHub Action Workflow companion** - The module is built to be a companion in GitHub Actions. It comes with PowerShell-flavored - [workflow-commands](https://docs.github.com/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions) and - is [context aware](https://docs.github.com/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs). - So it detects how it is being used and loads available information dynamically. You can provide it the `GITHUB_TOKEN`, a client ID and private key - for a GitHub App, or a user access token (fine-grained or classic). In addition to be a great local scripting companion, it also understands when - its run in GitHub Actions where it will automatically detect the event that triggered the workflow and provide the necessary context to commands. So - if you want to comment on the PR that triggered the workflow, that is the default it will use when writing a comment to the PR. - Use the [`GitHub-Script`](https://github.com/PSModule/GitHub-Script) action to get started. You can also use it in you own composite actions by - either using the [`GitHub-Script`](https://github.com/PSModule/GitHub-Script) action or by installing the module. -- **Automate GitHub** - The module works quite nicly in other automation too. If you want to build a bot that interacts with GitHub using Azure Function App the module - can easily be installed and used to automate tasks. It can also be used in scheduled tasks, CI/CD pipelines, and other automation scenarios. - -## Supported platforms - -As the module is built with the goal to support modern operators (assumed to use a newer OS), GitHub Actions and FunctionApps, the module -will **only support the latest LTS version of PowerShell on Windows, macOS, and Linux**. - -## Getting Started with GitHub PowerShell - -To dive into the world of GitHub automation with PowerShell, follow the sections below. - -### Installing the module - -Download and install the GitHub PowerShell module from the PowerShell Gallery with the following command: - -```powershell -Install-PSResource -Name GitHub -Repository PSGallery -TrustRepository -``` - -### Logging on - -Authenticate using your GitHub credentials or access tokens to begin executing commands. The module supports everything: - -- Personal authentication - - User Access Tokens (UATs) for personal accounts using both GitHub Apps and OAuth Apps. You can also bring your own app, so you dont have to use ours. - - Personal Access Tokens (PATs) using both classic and fine-grained scopes. -- Programmatic authentication - - GitHub Apps using the client ID and private key. - - Installation Access Tokens (IATs) for CI/CD pipelines, scheduled tasks and automation from other systems, like FunctionApps. - -#### Personal authentication - User access tokens - -This is the recommended method for authentication due to access tokens being short lived. -It opens a browser window and prompts you to log in to GitHub. Once you log in, you will be provided with -a code that you need to paste into the PowerShell console. The command already puts the code in your clipboard. -It uses a GitHub App to authenticate, which is more secure than using a personal access token. The GitHub App -is only granted access to the organizations or repositories you install it on. Visit the [GitHub Apps documentation](https://docs.github.com/developers/apps/about-apps) -to read more about GitHub Apps. You can also use a different GitHub App to issue user access tokens, check the section on -[Using a different GitHub App for issuing User access tokens](#using-a-different-github-app-for-issuing-user-access-tokens) for more information. - -```powershell -Connect-GitHubAccount -! We added the code to your clipboard: [AB55-FA2E] -Press Enter to open github.com in your browser...: #-> Press enter and paste the code in the browser window -✓ Logged in as octocat! -``` - -After this you will need to install the GitHub App on the repos you want to manage. You can do this by visiting the -[PowerShell for GitHub](https://github.com/apps/powershell-for-github) app page. - - - -#### Personal authentication - User access tokens with OAuth app - -This uses the same flow as above, but instead of using the GitHub App, it uses an OAuth app with long lived tokens. -During the signing you can also authorize the app to access your private repositories. -Visit the [OAuth apps documentation](https://docs.github.com/developers/apps/about-apps) to read more about OAuth apps on GitHub. +Install the module from the PowerShell Gallery: ```powershell -Connect-GitHubAccount -Mode OAuth - -! We added the code to your clipboard: [AB55-FA2E] -Press Enter to open github.com in your browser...: -✓ Logged in as octocat! +Install-PSResource -Name GitHub +Import-Module -Name GitHub ``` -#### Personal authentication - Personal Access Token - -This is the least secure method of authentication, but it is also the simplest. Running the `Connect-GitHubAccount` command -with the `-UseAccessToken` parameter will send you to the GitHub site where you can create a new personal access token. -Give it the access you need and paste it into the terminal. - -```powershell -Connect-GitHubAccount -UseAccessToken -! Enter your personal access token: **************************************** -✓ Logged in as octocat! -``` +## Documentation -#### Programmatic authentication - Installation Access Tokens (IATs) +Documentation is published at [psmodule.io/GitHub](https://psmodule.io/GitHub/). -The module also detects the presence of a system access token and uses that if it is present. -This is useful if you are running the module in a CI/CD pipeline or in a scheduled task. -The function looks for the `GH_TOKEN` and `GITHUB_TOKEN` environment variables (in order). - -```powershell -Connect-GitHubAccount -✓ Logged in as system! -``` - -You can also specify the token directly in the command. - -```powershell -Connect-GitHubAccount -Token '...' -✓ Logged in as octocat! -``` - -#### Using a GitHub App - -If you are using a GitHub App, you can use the `Connect-GitHubAccount` command to authenticate using the client ID and private key. - -```powershell -Connect-GitHubAccount -ClientID $ClientID -PrivateKey $PrivateKey -✓ Logged in as my-github-app! -``` - -Using this approach, the module will autogenerate a JWT every time you run a command. I.e. Get-GitHubApp. - -#### Using a GitHub App with Azure Key Vault - -For enhanced security, you can store your GitHub App's keys in Azure Key Vault and use that as way to signing the JWTs. -This approach requires a pre-authenticated session with either Azure CLI or Azure PowerShell. - -**Prerequisites:** -- Azure CLI authenticated session (`az login`) or Azure PowerShell authenticated session (`Connect-AzAccount`) -- GitHub App private key stored as a key in Azure Key Vault, with 'Sign' as a permitted operation -- Appropriate permissions to read keys from the Key Vault, like 'Key Vault Crypto User' - -**Using Azure CLI authentication:** - -```powershell -# Ensure you're authenticated with Azure CLI -az login - -# Connect using Key Vault key reference (URI with or without version) -Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-keyvault.vault.azure.net/keys/github-app-private-key' -✓ Logged in as my-github-app! -``` - -**Using Azure PowerShell authentication:** - -```powershell -# Ensure you're authenticated with Azure PowerShell -Connect-AzAccount - -# Connect using Key Vault key reference (URI with or without version) -Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-keyvault.vault.azure.net/keys/github-app-private-key' -✓ Logged in as my-github-app! -``` - -**Using Key Vault key reference with version:** - -```powershell -# Connect using Key Vault key reference with specific version -Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-keyvault.vault.azure.net/keys/github-app-private-key/abc123def456' -✓ Logged in as my-github-app! -``` - -This method ensures that your private key is securely stored in Azure Key Vault and never exposed in your scripts or configuration files. - -#### Using a different host - -If you are using GitHub Enterprise, you can use the `-Host` (or `-HostName`) parameter to specify the host you want to connect to. -This can be used in combination with all the other authentication methods. - -```powershell -Connect-GitHubAccount -Host 'https://github.local' -✓ Logged in as octocat! -``` - -Or you might be using GitHub Enterprise Cloud with Data Residency. - -```powershell -Connect-GitHubAccount -Host 'https://msx.ghe.com' -✓ Logged in as octocat! -``` - -#### Using a different GitHub App for issuing User access tokens - -Instead of using our default GitHub App, you can use a different GitHub App to issue user access tokens. -You can use the `-ClientID` parameters to specify the app you want to use. - -```powershell -Connect-GitHubAccount -Host 'https://msx.ghe.com' -ClientID 'lv123456789' -✓ Logged in as octocat! -``` - -#### Automatic token renewal - -The module automatically manages short‑lived tokens for GitHub Apps: - -- User access tokens (when you authenticate via a GitHub App) are short‑lived and include a refresh token. The module refreshes them automatically before/when they expire—no extra steps are required. -- App JWTs (when the context is a GitHub App) are generated and rotated automatically per call as needed. You never need to create or renew the JWT yourself. - -Note: Long‑lived tokens like classic/fine‑grained PATs and provided installation tokens (GH_TOKEN/GITHUB_TOKEN) are not refreshed by the module. - -### Command Exploration - -Familiarize yourself with the available cmdlets using the module's comprehensive documentation or inline help. +Use PowerShell help and command discovery for module details: ```powershell Get-Command -Module GitHub +Get-Help -Examples ``` -## References - -### Official GitHub Resources - -- [REST API Description](https://github.com/github/rest-api-description) -- [GitHub CLI Manual](https://cli.github.com/manual/) -- [GitHub Platform Samples](https://github.com/github/platform-samples) -- [Octokit](https://github.com/octokit) [rest.js API docs](https://octokit.github.io/rest.js/v20) - GitHub API clients for different languages. -- [actions/toolkit](https://github.com/actions/toolkit) - GitHub Actions Toolkit for JavaScript and TypeScript. -- [actions/github-script](https://github.com/actions/github-script) - GitHub Action for running ts/js octokit scripts. - -### General Web References - -- [Generic HTTP Status Codes (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) - -### Alternative GitHub PowerShell Modules +## Contributing -- [Microsoft's PowerShellForGitHub](https://github.com/microsoft/PowerShellForGitHub) -- [PSGitHub by pcgeek86](https://github.com/pcgeek86/PSGitHub) -- [GitHubActions by ebekker](https://github.com/ebekker/pwsh-github-action-tools) -- [powershell-devops by smokedlinq](https://github.com/smokedlinq/powershell-devops) -- [GitHubActionsToolkit by hugoalh-studio](https://github.com/hugoalh-studio/ghactions-toolkit-powershell) +Issues and pull requests are welcome. Please use the repository issue tracker to report bugs, request features, or discuss improvements. From 8e1e530708c530ddd24a66874424bc05be5e339f Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Mon, 6 Jul 2026 10:41:22 +0200 Subject: [PATCH 2/6] Address Copilot README review --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3382bb9a0..bf8599462 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Use PowerShell help and command discovery for module details: ```powershell Get-Command -Module GitHub -Get-Help -Examples +Get-Help 'CommandName' -Examples ``` ## Contributing From a0f705cc46b3c5344cb7285352c3d93c9ab961cc Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Mon, 6 Jul 2026 10:49:28 +0200 Subject: [PATCH 3/6] Address Copilot README review --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bf8599462..eb5312e16 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Use PowerShell help and command discovery for module details: ```powershell Get-Command -Module GitHub -Get-Help 'CommandName' -Examples +Get-Help Get-GitHubRepository -Examples ``` ## Contributing From 44f15a09f574628cdd4af241f0fbf45837df75f2 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Thu, 9 Jul 2026 06:15:28 +0200 Subject: [PATCH 4/6] Preserve authentication guide and supported use-cases Applies the content-preserving README default: keeps the highlights/use-cases, supported platforms, and a condensed authentication guide (interactive, PAT, GitHub Actions token, GitHub App, Azure Key Vault, GHES/GHEC host, automatic token renewal), instead of deleting them. --- README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 65 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index eb5312e16..35cd29eec 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,16 @@ # GitHub -GitHub is a PowerShell module for interacting with GitHub, both interactively and in automation. +GitHub is a PowerShell module for interacting with GitHub, both interactively and in automation. It gives operators, administrators, and GitHub Actions authors a PowerShell-flavored way to manage GitHub across GitHub.com, GitHub Enterprise Cloud (GHEC, including GHE.com and data residency), and GitHub Enterprise Server (GHES). + +## Highlights + +- **Operate any GitHub environment** — connect with multiple accounts and token types across github.com, GHEC, and GHES. +- **A GitHub Actions companion** — context-aware, with PowerShell-flavored [workflow commands](https://docs.github.com/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions). It detects the event that triggered the workflow and supplies the right context to commands automatically. Get started with the [`GitHub-Script`](https://github.com/PSModule/GitHub-Script) action. +- **Automate GitHub anywhere** — bots, Azure Function Apps, scheduled tasks, and other CI/CD pipelines. + +## Prerequisites + +Supports the latest LTS version of PowerShell on Windows, macOS, and Linux. ## Installation @@ -11,6 +21,54 @@ Install-PSResource -Name GitHub Import-Module -Name GitHub ``` +## Authentication + +Connect with `Connect-GitHubAccount`. The module supports interactive and programmatic authentication and manages short-lived tokens for you. + +Interactive (recommended) uses a browser-based device flow backed by a GitHub App. Tokens are short-lived and refreshed automatically: + +```powershell +Connect-GitHubAccount +``` + +Other interactive options use an OAuth app or a personal access token: + +```powershell +Connect-GitHubAccount -Mode OAuth # OAuth app instead of the GitHub App +Connect-GitHubAccount -UseAccessToken # paste a classic or fine-grained PAT +``` + +Programmatic authentication covers CI/CD, scheduled tasks, and apps. In GitHub Actions the module automatically uses `GH_TOKEN` or `GITHUB_TOKEN` when present: + +```powershell +Connect-GitHubAccount # uses GH_TOKEN / GITHUB_TOKEN when available +Connect-GitHubAccount -ClientID $ClientID -PrivateKey $PrivateKey # GitHub App; a JWT is generated per call +``` + +For GitHub Apps, you can keep the private key in Azure Key Vault instead of exposing it in scripts. This requires an existing `az login` or `Connect-AzAccount` session: + +```powershell +Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-vault.vault.azure.net/keys/github-app-key' +``` + +Connect to GitHub Enterprise Server, or to GHEC with data residency, with `-Host` — optionally with your own app's `-ClientID`: + +```powershell +Connect-GitHubAccount -Host 'https://github.local' +Connect-GitHubAccount -Host 'https://msx.ghe.com' -ClientID 'lv123456789' +``` + +The module refreshes GitHub App user access tokens and rotates app JWTs automatically. Long-lived PATs and provided installation tokens (`GH_TOKEN` / `GITHUB_TOKEN`) are used as-is and are not refreshed. + +## Usage + +Discover the available commands and start managing GitHub: + +```powershell +Get-Command -Module GitHub +Get-GitHubRepository -Owner 'PSModule' -Name 'GitHub' +``` + ## Documentation Documentation is published at [psmodule.io/GitHub](https://psmodule.io/GitHub/). @@ -19,9 +77,12 @@ Use PowerShell help and command discovery for module details: ```powershell Get-Command -Module GitHub -Get-Help Get-GitHubRepository -Examples +Get-Help -Name Get-GitHubRepository -Examples ``` -## Contributing +## References -Issues and pull requests are welcome. Please use the repository issue tracker to report bugs, request features, or discuss improvements. +- [REST API Description](https://github.com/github/rest-api-description) +- [GitHub CLI Manual](https://cli.github.com/manual/) +- [Octokit](https://github.com/octokit) — GitHub API clients for many languages +- [actions/toolkit](https://github.com/actions/toolkit) — GitHub Actions toolkit for JavaScript and TypeScript From 303e9bba1b7e9fc422aec61e76b56c9153dd7536 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Thu, 9 Jul 2026 06:51:44 +0200 Subject: [PATCH 5/6] Preserve full README content; add generated-docs pointer The README is the published psmodule.io landing page and the only home for the getting-started and authentication guide (device flow, OAuth, PAT, GitHub App, Azure Key Vault, GHES/GHEC host, token renewal). Restores that content and adds a Documentation section pointing to the generated command reference and Get-Help. --- README.md | 220 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 185 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 35cd29eec..1235915d8 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,213 @@ -# GitHub +# GitHub PowerShell -GitHub is a PowerShell module for interacting with GitHub, both interactively and in automation. It gives operators, administrators, and GitHub Actions authors a PowerShell-flavored way to manage GitHub across GitHub.com, GitHub Enterprise Cloud (GHEC, including GHE.com and data residency), and GitHub Enterprise Server (GHES). +The module provides a PowerShell-flavored approach to managing and automating your GitHub environments. It's tailored for developers, administrators, +and GitHub enthusiasts who want to use PowerShell to integrate or manage GitHub seamlessly. -## Highlights +## Supported use-cases -- **Operate any GitHub environment** — connect with multiple accounts and token types across github.com, GHEC, and GHES. -- **A GitHub Actions companion** — context-aware, with PowerShell-flavored [workflow commands](https://docs.github.com/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions). It detects the event that triggered the workflow and supplies the right context to commands automatically. Get started with the [`GitHub-Script`](https://github.com/PSModule/GitHub-Script) action. -- **Automate GitHub anywhere** — bots, Azure Function Apps, scheduled tasks, and other CI/CD pipelines. +- **Operate any GitHub environment** + As an operator of any type of GitHub environment, you can use this module to automate your workflows and tasks. The module supports connecting + with multiple accounts; be that GitHub (public, github.com), GitHub Enterprise Cloud (GHEC, including GHE.com) and GitHub Enterprise Server (GHES). +- **A great GitHub Action Workflow companion** + The module is built to be a companion in GitHub Actions. It comes with PowerShell-flavored + [workflow-commands](https://docs.github.com/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions) and + is [context aware](https://docs.github.com/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs). + So it detects how it is being used and loads available information dynamically. You can provide it the `GITHUB_TOKEN`, a client ID and private key + for a GitHub App, or a user access token (fine-grained or classic). In addition to be a great local scripting companion, it also understands when + its run in GitHub Actions where it will automatically detect the event that triggered the workflow and provide the necessary context to commands. So + if you want to comment on the PR that triggered the workflow, that is the default it will use when writing a comment to the PR. + Use the [`GitHub-Script`](https://github.com/PSModule/GitHub-Script) action to get started. You can also use it in you own composite actions by + either using the [`GitHub-Script`](https://github.com/PSModule/GitHub-Script) action or by installing the module. +- **Automate GitHub** + The module works quite nicly in other automation too. If you want to build a bot that interacts with GitHub using Azure Function App the module + can easily be installed and used to automate tasks. It can also be used in scheduled tasks, CI/CD pipelines, and other automation scenarios. -## Prerequisites +## Supported platforms -Supports the latest LTS version of PowerShell on Windows, macOS, and Linux. +As the module is built with the goal to support modern operators (assumed to use a newer OS), GitHub Actions and FunctionApps, the module +will **only support the latest LTS version of PowerShell on Windows, macOS, and Linux**. -## Installation +## Getting Started with GitHub PowerShell -Install the module from the PowerShell Gallery: +To dive into the world of GitHub automation with PowerShell, follow the sections below. + +### Installing the module + +Download and install the GitHub PowerShell module from the PowerShell Gallery with the following command: ```powershell -Install-PSResource -Name GitHub -Import-Module -Name GitHub +Install-PSResource -Name GitHub -Repository PSGallery -TrustRepository ``` -## Authentication +### Logging on + +Authenticate using your GitHub credentials or access tokens to begin executing commands. The module supports everything: + +- Personal authentication + - User Access Tokens (UATs) for personal accounts using both GitHub Apps and OAuth Apps. You can also bring your own app, so you dont have to use ours. + - Personal Access Tokens (PATs) using both classic and fine-grained scopes. +- Programmatic authentication + - GitHub Apps using the client ID and private key. + - Installation Access Tokens (IATs) for CI/CD pipelines, scheduled tasks and automation from other systems, like FunctionApps. -Connect with `Connect-GitHubAccount`. The module supports interactive and programmatic authentication and manages short-lived tokens for you. +#### Personal authentication - User access tokens -Interactive (recommended) uses a browser-based device flow backed by a GitHub App. Tokens are short-lived and refreshed automatically: +This is the recommended method for authentication due to access tokens being short lived. +It opens a browser window and prompts you to log in to GitHub. Once you log in, you will be provided with +a code that you need to paste into the PowerShell console. The command already puts the code in your clipboard. +It uses a GitHub App to authenticate, which is more secure than using a personal access token. The GitHub App +is only granted access to the organizations or repositories you install it on. Visit the [GitHub Apps documentation](https://docs.github.com/developers/apps/about-apps) +to read more about GitHub Apps. You can also use a different GitHub App to issue user access tokens, check the section on +[Using a different GitHub App for issuing User access tokens](#using-a-different-github-app-for-issuing-user-access-tokens) for more information. ```powershell Connect-GitHubAccount +! We added the code to your clipboard: [AB55-FA2E] +Press Enter to open github.com in your browser...: #-> Press enter and paste the code in the browser window +✓ Logged in as octocat! ``` -Other interactive options use an OAuth app or a personal access token: +After this you will need to install the GitHub App on the repos you want to manage. You can do this by visiting the +[PowerShell for GitHub](https://github.com/apps/powershell-for-github) app page. + + + +#### Personal authentication - User access tokens with OAuth app + +This uses the same flow as above, but instead of using the GitHub App, it uses an OAuth app with long lived tokens. +During the signing you can also authorize the app to access your private repositories. +Visit the [OAuth apps documentation](https://docs.github.com/developers/apps/about-apps) to read more about OAuth apps on GitHub. ```powershell -Connect-GitHubAccount -Mode OAuth # OAuth app instead of the GitHub App -Connect-GitHubAccount -UseAccessToken # paste a classic or fine-grained PAT +Connect-GitHubAccount -Mode OAuth + +! We added the code to your clipboard: [AB55-FA2E] +Press Enter to open github.com in your browser...: +✓ Logged in as octocat! ``` -Programmatic authentication covers CI/CD, scheduled tasks, and apps. In GitHub Actions the module automatically uses `GH_TOKEN` or `GITHUB_TOKEN` when present: +#### Personal authentication - Personal Access Token + +This is the least secure method of authentication, but it is also the simplest. Running the `Connect-GitHubAccount` command +with the `-UseAccessToken` parameter will send you to the GitHub site where you can create a new personal access token. +Give it the access you need and paste it into the terminal. ```powershell -Connect-GitHubAccount # uses GH_TOKEN / GITHUB_TOKEN when available -Connect-GitHubAccount -ClientID $ClientID -PrivateKey $PrivateKey # GitHub App; a JWT is generated per call +Connect-GitHubAccount -UseAccessToken +! Enter your personal access token: **************************************** +✓ Logged in as octocat! ``` -For GitHub Apps, you can keep the private key in Azure Key Vault instead of exposing it in scripts. This requires an existing `az login` or `Connect-AzAccount` session: +#### Programmatic authentication - Installation Access Tokens (IATs) + +The module also detects the presence of a system access token and uses that if it is present. +This is useful if you are running the module in a CI/CD pipeline or in a scheduled task. +The function looks for the `GH_TOKEN` and `GITHUB_TOKEN` environment variables (in order). ```powershell -Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-vault.vault.azure.net/keys/github-app-key' +Connect-GitHubAccount +✓ Logged in as system! ``` -Connect to GitHub Enterprise Server, or to GHEC with data residency, with `-Host` — optionally with your own app's `-ClientID`: +You can also specify the token directly in the command. + +```powershell +Connect-GitHubAccount -Token '...' +✓ Logged in as octocat! +``` + +#### Using a GitHub App + +If you are using a GitHub App, you can use the `Connect-GitHubAccount` command to authenticate using the client ID and private key. + +```powershell +Connect-GitHubAccount -ClientID $ClientID -PrivateKey $PrivateKey +✓ Logged in as my-github-app! +``` + +Using this approach, the module will autogenerate a JWT every time you run a command. I.e. Get-GitHubApp. + +#### Using a GitHub App with Azure Key Vault + +For enhanced security, you can store your GitHub App's keys in Azure Key Vault and use that as way to signing the JWTs. +This approach requires a pre-authenticated session with either Azure CLI or Azure PowerShell. + +**Prerequisites:** +- Azure CLI authenticated session (`az login`) or Azure PowerShell authenticated session (`Connect-AzAccount`) +- GitHub App private key stored as a key in Azure Key Vault, with 'Sign' as a permitted operation +- Appropriate permissions to read keys from the Key Vault, like 'Key Vault Crypto User' + +**Using Azure CLI authentication:** + +```powershell +# Ensure you're authenticated with Azure CLI +az login + +# Connect using Key Vault key reference (URI with or without version) +Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-keyvault.vault.azure.net/keys/github-app-private-key' +✓ Logged in as my-github-app! +``` + +**Using Azure PowerShell authentication:** + +```powershell +# Ensure you're authenticated with Azure PowerShell +Connect-AzAccount + +# Connect using Key Vault key reference (URI with or without version) +Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-keyvault.vault.azure.net/keys/github-app-private-key' +✓ Logged in as my-github-app! +``` + +**Using Key Vault key reference with version:** + +```powershell +# Connect using Key Vault key reference with specific version +Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-keyvault.vault.azure.net/keys/github-app-private-key/abc123def456' +✓ Logged in as my-github-app! +``` + +This method ensures that your private key is securely stored in Azure Key Vault and never exposed in your scripts or configuration files. + +#### Using a different host + +If you are using GitHub Enterprise, you can use the `-Host` (or `-HostName`) parameter to specify the host you want to connect to. +This can be used in combination with all the other authentication methods. ```powershell Connect-GitHubAccount -Host 'https://github.local' -Connect-GitHubAccount -Host 'https://msx.ghe.com' -ClientID 'lv123456789' +✓ Logged in as octocat! ``` -The module refreshes GitHub App user access tokens and rotates app JWTs automatically. Long-lived PATs and provided installation tokens (`GH_TOKEN` / `GITHUB_TOKEN`) are used as-is and are not refreshed. +Or you might be using GitHub Enterprise Cloud with Data Residency. + +```powershell +Connect-GitHubAccount -Host 'https://msx.ghe.com' +✓ Logged in as octocat! +``` -## Usage +#### Using a different GitHub App for issuing User access tokens -Discover the available commands and start managing GitHub: +Instead of using our default GitHub App, you can use a different GitHub App to issue user access tokens. +You can use the `-ClientID` parameters to specify the app you want to use. ```powershell -Get-Command -Module GitHub -Get-GitHubRepository -Owner 'PSModule' -Name 'GitHub' +Connect-GitHubAccount -Host 'https://msx.ghe.com' -ClientID 'lv123456789' +✓ Logged in as octocat! ``` -## Documentation +#### Automatic token renewal + +The module automatically manages short‑lived tokens for GitHub Apps: + +- User access tokens (when you authenticate via a GitHub App) are short‑lived and include a refresh token. The module refreshes them automatically before/when they expire—no extra steps are required. +- App JWTs (when the context is a GitHub App) are generated and rotated automatically per call as needed. You never need to create or renew the JWT yourself. -Documentation is published at [psmodule.io/GitHub](https://psmodule.io/GitHub/). +Note: Long‑lived tokens like classic/fine‑grained PATs and provided installation tokens (GH_TOKEN/GITHUB_TOKEN) are not refreshed by the module. -Use PowerShell help and command discovery for module details: +## Documentation + +Every command ships with full reference documentation, generated from its comment-based help and published at [psmodule.io/GitHub](https://psmodule.io/GitHub/). Explore the commands and read detailed help directly from PowerShell: ```powershell Get-Command -Module GitHub @@ -82,7 +216,23 @@ Get-Help -Name Get-GitHubRepository -Examples ## References +### Official GitHub Resources + - [REST API Description](https://github.com/github/rest-api-description) - [GitHub CLI Manual](https://cli.github.com/manual/) -- [Octokit](https://github.com/octokit) — GitHub API clients for many languages -- [actions/toolkit](https://github.com/actions/toolkit) — GitHub Actions toolkit for JavaScript and TypeScript +- [GitHub Platform Samples](https://github.com/github/platform-samples) +- [Octokit](https://github.com/octokit) [rest.js API docs](https://octokit.github.io/rest.js/v20) - GitHub API clients for different languages. +- [actions/toolkit](https://github.com/actions/toolkit) - GitHub Actions Toolkit for JavaScript and TypeScript. +- [actions/github-script](https://github.com/actions/github-script) - GitHub Action for running ts/js octokit scripts. + +### General Web References + +- [Generic HTTP Status Codes (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) + +### Alternative GitHub PowerShell Modules + +- [Microsoft's PowerShellForGitHub](https://github.com/microsoft/PowerShellForGitHub) +- [PSGitHub by pcgeek86](https://github.com/pcgeek86/PSGitHub) +- [GitHubActions by ebekker](https://github.com/ebekker/pwsh-github-action-tools) +- [powershell-devops by smokedlinq](https://github.com/smokedlinq/powershell-devops) +- [GitHubActionsToolkit by hugoalh-studio](https://github.com/hugoalh-studio/ghactions-toolkit-powershell) From 1d38164d2ff2a92245497f6faf714607b41f8c62 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Thu, 9 Jul 2026 13:21:13 +0200 Subject: [PATCH 6/6] Move authentication guide to a published Auth group page Relocates the full authentication guide from the README into src/functions/public/Auth/Auth.md, which the doc build publishes as a group page at psmodule.io/GitHub/Functions/Auth/Auth/ (same pattern as Template-PSModule). The README keeps a concise Authentication summary that links to it. Docs live in the code and publish automatically; nothing is lost. --- README.md | 160 +---------------------------- src/functions/public/Auth/Auth.md | 164 ++++++++++++++++++++++++++++++ 2 files changed, 166 insertions(+), 158 deletions(-) create mode 100644 src/functions/public/Auth/Auth.md diff --git a/README.md b/README.md index 1235915d8..0266c38c2 100644 --- a/README.md +++ b/README.md @@ -41,169 +41,13 @@ Install-PSResource -Name GitHub -Repository PSGallery -TrustRepository ### Logging on -Authenticate using your GitHub credentials or access tokens to begin executing commands. The module supports everything: - -- Personal authentication - - User Access Tokens (UATs) for personal accounts using both GitHub Apps and OAuth Apps. You can also bring your own app, so you dont have to use ours. - - Personal Access Tokens (PATs) using both classic and fine-grained scopes. -- Programmatic authentication - - GitHub Apps using the client ID and private key. - - Installation Access Tokens (IATs) for CI/CD pipelines, scheduled tasks and automation from other systems, like FunctionApps. - -#### Personal authentication - User access tokens - -This is the recommended method for authentication due to access tokens being short lived. -It opens a browser window and prompts you to log in to GitHub. Once you log in, you will be provided with -a code that you need to paste into the PowerShell console. The command already puts the code in your clipboard. -It uses a GitHub App to authenticate, which is more secure than using a personal access token. The GitHub App -is only granted access to the organizations or repositories you install it on. Visit the [GitHub Apps documentation](https://docs.github.com/developers/apps/about-apps) -to read more about GitHub Apps. You can also use a different GitHub App to issue user access tokens, check the section on -[Using a different GitHub App for issuing User access tokens](#using-a-different-github-app-for-issuing-user-access-tokens) for more information. - -```powershell -Connect-GitHubAccount -! We added the code to your clipboard: [AB55-FA2E] -Press Enter to open github.com in your browser...: #-> Press enter and paste the code in the browser window -✓ Logged in as octocat! -``` - -After this you will need to install the GitHub App on the repos you want to manage. You can do this by visiting the -[PowerShell for GitHub](https://github.com/apps/powershell-for-github) app page. - - - -#### Personal authentication - User access tokens with OAuth app - -This uses the same flow as above, but instead of using the GitHub App, it uses an OAuth app with long lived tokens. -During the signing you can also authorize the app to access your private repositories. -Visit the [OAuth apps documentation](https://docs.github.com/developers/apps/about-apps) to read more about OAuth apps on GitHub. - -```powershell -Connect-GitHubAccount -Mode OAuth - -! We added the code to your clipboard: [AB55-FA2E] -Press Enter to open github.com in your browser...: -✓ Logged in as octocat! -``` - -#### Personal authentication - Personal Access Token - -This is the least secure method of authentication, but it is also the simplest. Running the `Connect-GitHubAccount` command -with the `-UseAccessToken` parameter will send you to the GitHub site where you can create a new personal access token. -Give it the access you need and paste it into the terminal. - -```powershell -Connect-GitHubAccount -UseAccessToken -! Enter your personal access token: **************************************** -✓ Logged in as octocat! -``` - -#### Programmatic authentication - Installation Access Tokens (IATs) - -The module also detects the presence of a system access token and uses that if it is present. -This is useful if you are running the module in a CI/CD pipeline or in a scheduled task. -The function looks for the `GH_TOKEN` and `GITHUB_TOKEN` environment variables (in order). +Authenticate with `Connect-GitHubAccount`. The recommended method is an interactive browser sign-in backed by a GitHub App, with short-lived tokens that refresh automatically: ```powershell Connect-GitHubAccount -✓ Logged in as system! -``` - -You can also specify the token directly in the command. - -```powershell -Connect-GitHubAccount -Token '...' -✓ Logged in as octocat! -``` - -#### Using a GitHub App - -If you are using a GitHub App, you can use the `Connect-GitHubAccount` command to authenticate using the client ID and private key. - -```powershell -Connect-GitHubAccount -ClientID $ClientID -PrivateKey $PrivateKey -✓ Logged in as my-github-app! -``` - -Using this approach, the module will autogenerate a JWT every time you run a command. I.e. Get-GitHubApp. - -#### Using a GitHub App with Azure Key Vault - -For enhanced security, you can store your GitHub App's keys in Azure Key Vault and use that as way to signing the JWTs. -This approach requires a pre-authenticated session with either Azure CLI or Azure PowerShell. - -**Prerequisites:** -- Azure CLI authenticated session (`az login`) or Azure PowerShell authenticated session (`Connect-AzAccount`) -- GitHub App private key stored as a key in Azure Key Vault, with 'Sign' as a permitted operation -- Appropriate permissions to read keys from the Key Vault, like 'Key Vault Crypto User' - -**Using Azure CLI authentication:** - -```powershell -# Ensure you're authenticated with Azure CLI -az login - -# Connect using Key Vault key reference (URI with or without version) -Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-keyvault.vault.azure.net/keys/github-app-private-key' -✓ Logged in as my-github-app! -``` - -**Using Azure PowerShell authentication:** - -```powershell -# Ensure you're authenticated with Azure PowerShell -Connect-AzAccount - -# Connect using Key Vault key reference (URI with or without version) -Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-keyvault.vault.azure.net/keys/github-app-private-key' -✓ Logged in as my-github-app! -``` - -**Using Key Vault key reference with version:** - -```powershell -# Connect using Key Vault key reference with specific version -Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-keyvault.vault.azure.net/keys/github-app-private-key/abc123def456' -✓ Logged in as my-github-app! -``` - -This method ensures that your private key is securely stored in Azure Key Vault and never exposed in your scripts or configuration files. - -#### Using a different host - -If you are using GitHub Enterprise, you can use the `-Host` (or `-HostName`) parameter to specify the host you want to connect to. -This can be used in combination with all the other authentication methods. - -```powershell -Connect-GitHubAccount -Host 'https://github.local' -✓ Logged in as octocat! -``` - -Or you might be using GitHub Enterprise Cloud with Data Residency. - -```powershell -Connect-GitHubAccount -Host 'https://msx.ghe.com' -✓ Logged in as octocat! ``` -#### Using a different GitHub App for issuing User access tokens - -Instead of using our default GitHub App, you can use a different GitHub App to issue user access tokens. -You can use the `-ClientID` parameters to specify the app you want to use. - -```powershell -Connect-GitHubAccount -Host 'https://msx.ghe.com' -ClientID 'lv123456789' -✓ Logged in as octocat! -``` - -#### Automatic token renewal - -The module automatically manages short‑lived tokens for GitHub Apps: - -- User access tokens (when you authenticate via a GitHub App) are short‑lived and include a refresh token. The module refreshes them automatically before/when they expire—no extra steps are required. -- App JWTs (when the context is a GitHub App) are generated and rotated automatically per call as needed. You never need to create or renew the JWT yourself. - -Note: Long‑lived tokens like classic/fine‑grained PATs and provided installation tokens (GH_TOKEN/GITHUB_TOKEN) are not refreshed by the module. +The module supports many methods: OAuth apps, personal access tokens (classic and fine-grained), GitHub Apps (client ID and private key or an Azure Key Vault key), automatic use of `GH_TOKEN`/`GITHUB_TOKEN` in GitHub Actions, and GitHub Enterprise Server or data-residency hosts via `-Host`. See the full [Authentication guide](https://psmodule.io/GitHub/Functions/Auth/Auth/) for every method, Key Vault setup, custom apps, and automatic token renewal. ## Documentation diff --git a/src/functions/public/Auth/Auth.md b/src/functions/public/Auth/Auth.md new file mode 100644 index 000000000..d8538c19d --- /dev/null +++ b/src/functions/public/Auth/Auth.md @@ -0,0 +1,164 @@ +# Authentication + +Authenticate using your GitHub credentials or access tokens to begin executing commands. The module supports everything: + +- Personal authentication + - User Access Tokens (UATs) for personal accounts using both GitHub Apps and OAuth Apps. You can also bring your own app, so you dont have to use ours. + - Personal Access Tokens (PATs) using both classic and fine-grained scopes. +- Programmatic authentication + - GitHub Apps using the client ID and private key. + - Installation Access Tokens (IATs) for CI/CD pipelines, scheduled tasks and automation from other systems, like FunctionApps. + +## Personal authentication - User access tokens + +This is the recommended method for authentication due to access tokens being short lived. +It opens a browser window and prompts you to log in to GitHub. Once you log in, you will be provided with +a code that you need to paste into the PowerShell console. The command already puts the code in your clipboard. +It uses a GitHub App to authenticate, which is more secure than using a personal access token. The GitHub App +is only granted access to the organizations or repositories you install it on. Visit the [GitHub Apps documentation](https://docs.github.com/developers/apps/about-apps) +to read more about GitHub Apps. You can also use a different GitHub App to issue user access tokens, check the section on +[Using a different GitHub App for issuing User access tokens](#using-a-different-github-app-for-issuing-user-access-tokens) for more information. + +```powershell +Connect-GitHubAccount +! We added the code to your clipboard: [AB55-FA2E] +Press Enter to open github.com in your browser...: #-> Press enter and paste the code in the browser window +✓ Logged in as octocat! +``` + +After this you will need to install the GitHub App on the repos you want to manage. You can do this by visiting the +[PowerShell for GitHub](https://github.com/apps/powershell-for-github) app page. + +## Personal authentication - User access tokens with OAuth app + +This uses the same flow as above, but instead of using the GitHub App, it uses an OAuth app with long lived tokens. +During the signing you can also authorize the app to access your private repositories. +Visit the [OAuth apps documentation](https://docs.github.com/developers/apps/about-apps) to read more about OAuth apps on GitHub. + +```powershell +Connect-GitHubAccount -Mode OAuth + +! We added the code to your clipboard: [AB55-FA2E] +Press Enter to open github.com in your browser...: +✓ Logged in as octocat! +``` + +## Personal authentication - Personal Access Token + +This is the least secure method of authentication, but it is also the simplest. Running the `Connect-GitHubAccount` command +with the `-UseAccessToken` parameter will send you to the GitHub site where you can create a new personal access token. +Give it the access you need and paste it into the terminal. + +```powershell +Connect-GitHubAccount -UseAccessToken +! Enter your personal access token: **************************************** +✓ Logged in as octocat! +``` + +## Programmatic authentication - Installation Access Tokens (IATs) + +The module also detects the presence of a system access token and uses that if it is present. +This is useful if you are running the module in a CI/CD pipeline or in a scheduled task. +The function looks for the `GH_TOKEN` and `GITHUB_TOKEN` environment variables (in order). + +```powershell +Connect-GitHubAccount +✓ Logged in as system! +``` + +You can also specify the token directly in the command. + +```powershell +Connect-GitHubAccount -Token '...' +✓ Logged in as octocat! +``` + +## Using a GitHub App + +If you are using a GitHub App, you can use the `Connect-GitHubAccount` command to authenticate using the client ID and private key. + +```powershell +Connect-GitHubAccount -ClientID $ClientID -PrivateKey $PrivateKey +✓ Logged in as my-github-app! +``` + +Using this approach, the module will autogenerate a JWT every time you run a command. I.e. Get-GitHubApp. + +## Using a GitHub App with Azure Key Vault + +For enhanced security, you can store your GitHub App's keys in Azure Key Vault and use that as way to signing the JWTs. +This approach requires a pre-authenticated session with either Azure CLI or Azure PowerShell. + +**Prerequisites:** + +- Azure CLI authenticated session (`az login`) or Azure PowerShell authenticated session (`Connect-AzAccount`) +- GitHub App private key stored as a key in Azure Key Vault, with 'Sign' as a permitted operation +- Appropriate permissions to read keys from the Key Vault, like 'Key Vault Crypto User' + +**Using Azure CLI authentication:** + +```powershell +# Ensure you're authenticated with Azure CLI +az login + +# Connect using Key Vault key reference (URI with or without version) +Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-keyvault.vault.azure.net/keys/github-app-private-key' +✓ Logged in as my-github-app! +``` + +**Using Azure PowerShell authentication:** + +```powershell +# Ensure you're authenticated with Azure PowerShell +Connect-AzAccount + +# Connect using Key Vault key reference (URI with or without version) +Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-keyvault.vault.azure.net/keys/github-app-private-key' +✓ Logged in as my-github-app! +``` + +**Using Key Vault key reference with version:** + +```powershell +# Connect using Key Vault key reference with specific version +Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-keyvault.vault.azure.net/keys/github-app-private-key/abc123def456' +✓ Logged in as my-github-app! +``` + +This method ensures that your private key is securely stored in Azure Key Vault and never exposed in your scripts or configuration files. + +## Using a different host + +If you are using GitHub Enterprise, you can use the `-Host` (or `-HostName`) parameter to specify the host you want to connect to. +This can be used in combination with all the other authentication methods. + +```powershell +Connect-GitHubAccount -Host 'https://github.local' +✓ Logged in as octocat! +``` + +Or you might be using GitHub Enterprise Cloud with Data Residency. + +```powershell +Connect-GitHubAccount -Host 'https://msx.ghe.com' +✓ Logged in as octocat! +``` + +## Using a different GitHub App for issuing User access tokens + +Instead of using our default GitHub App, you can use a different GitHub App to issue user access tokens. +You can use the `-ClientID` parameters to specify the app you want to use. + +```powershell +Connect-GitHubAccount -Host 'https://msx.ghe.com' -ClientID 'lv123456789' +✓ Logged in as octocat! +``` + +## Automatic token renewal + +The module automatically manages short‑lived tokens for GitHub Apps: + +- User access tokens (when you authenticate via a GitHub App) are short‑lived and include a refresh token. The module refreshes them automatically before/when they expire—no extra steps are required. +- App JWTs (when the context is a GitHub App) are generated and rotated automatically per call as needed. You never need to create or renew the JWT yourself. + +Note: Long‑lived tokens like classic/fine‑grained PATs and provided installation tokens (GH_TOKEN/GITHUB_TOKEN) are not refreshed by the module.