📖 [Docs]: README pages now use the standard module landing-page format#638
Open
Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
Open
📖 [Docs]: README pages now use the standard module landing-page format#638Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
Conversation
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 06:30
View session
Contributor
There was a problem hiding this comment.
Pull request overview
This PR standardizes README.md into a lightweight landing page aligned with the Template-PSModule default, pushing detailed usage guidance into PowerShell help and the generated module documentation.
Changes:
- Replaces the long-form README with a concise module overview.
- Simplifies installation instructions and points users to
psmodule.iofor full documentation. - Adds a brief contributing section directing users to the issue tracker.
Contributor
Super-linter summary
All files and directories linted successfully For more information, see the GitHub Actions workflow run Powered by Super-linter |
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 08:25
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 08:26
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 08:28
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 08:33
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 08:38
View session
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
README.md:28
- The file ends with a blank line containing trailing whitespace, which can trigger markdown/style linters. Remove the trailing spaces (and optionally the extra blank line).
Issues and pull requests are welcome. Please use the repository issue tracker to report bugs, request features, or discuss improvements.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 08:43
View session
Contributor
Super-linter summary
All files and directories linted successfully For more information, see the GitHub Actions workflow run Powered by Super-linter |
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 08:46
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 08:48
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 6, 2026 08:50
View session
Contributor
Super-linter summary
All files and directories linted successfully For more information, see the GitHub Actions workflow run Powered by Super-linter |
Marius Storhaug (MariusStorhaug)
changed the title
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.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 04:15
View session
| ```powershell | ||
| Connect-GitHubAccount | ||
| ✓ Logged in as system! | ||
| Connect-GitHubAccount -Mode OAuth # OAuth app instead of the GitHub App |
Contributor
Super-linter summary
All files and directories linted successfully For more information, see the GitHub Actions workflow run Powered by Super-linter |
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.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 04:57
View session
Contributor
Super-linter summary
All files and directories linted successfully For more information, see the GitHub Actions workflow run Powered by Super-linter |
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.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 11:21
View session
| 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. |
Comment on lines
+34
to
+36
| 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. |
Comment on lines
+44
to
+50
| 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. |
Contributor
Super-linter summary
All files and directories linted successfully For more information, see the GitHub Actions workflow run Powered by Super-linter |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Keeps the full README content — the README is the published psmodule.io/GitHub landing page and the only home for the getting-started and authentication guide (device flow, OAuth, PAT,
GH_TOKEN/GITHUB_TOKEN, GitHub App, Azure Key Vault, GHES/GHEC-Host, custom app, automatic token renewal), supported use-cases, platforms, and references.Change is additive: folds the old Command Exploration subsection into a Documentation section that also points to the generated command reference and
Get-Helpwith a real cmdlet.Follows the updated README default (PSModule/docs#61). The per-command reference is generated separately from comment-based help; narrative content stays in the README because that is where it publishes.