From 64b5298c155ca9cb6036dd92553aa44760e4f4d3 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 6 Nov 2024 12:31:48 +0100 Subject: [PATCH 1/7] Cleanup outdated 'about-topics' --- src/en-US/about_Auth.help.txt | 45 -------------- src/en-US/about_Config.help.txt | 107 -------------------------------- 2 files changed, 152 deletions(-) delete mode 100644 src/en-US/about_Auth.help.txt delete mode 100644 src/en-US/about_Config.help.txt diff --git a/src/en-US/about_Auth.help.txt b/src/en-US/about_Auth.help.txt deleted file mode 100644 index 2571c556d..000000000 --- a/src/en-US/about_Auth.help.txt +++ /dev/null @@ -1,45 +0,0 @@ -TOPIC - about_Auth - -SHORT DESCRIPTION - Describes the authentication methods provided in the PowerShell module for interacting with GitHub's REST API. - -LONG DESCRIPTION - This module provides several functions to manage authentication for GitHub's REST API. There are primarily two ways to authenticate: - - 1. GitHub Device Flow: This method prompts the user to visit a specific URL on GitHub where they must enter a user verification code. Once this is done, the module retrieves the necessary access tokens to make authenticated API requests. - - 2. Personal Access Token: The user can provide a Personal Access Token (PAT) to authenticate. This PAT allows the module to interact with the API on the user's behalf. The module can automatically use environment variables `GH_TOKEN` or `GITHUB_TOKEN` if they are present. - - The module also provides functionalities to refresh the access token and to disconnect or logout from the GitHub account. - -EXAMPLES - Example 1: - Connect-GitHubAccount - Connects to GitHub using the device flow login. You'll be prompted to visit a specific URL on GitHub and enter the provided user verification code. - - Example 2: - Connect-GitHubAccount -AccessToken 'ghp_####' - Connects to GitHub using a provided personal access token (PAT). - - Example 3: - Connect-GitHubAccount -Refresh - Refreshes the access token for continued session validity. - - Example 4: - Disconnect-GitHubAccount - Disconnects from GitHub and removes the current GitHub configuration. - - Example 5 (Automatic login using environment variables): - If either the `GH_TOKEN` or `GITHUB_TOKEN` environment variables are set, the module will automatically use them for authentication during module initialization. - -KEYWORDS - GitHub, Authentication, Device Flow, Personal Access Token, PowerShell, REST API - -SEE ALSO - For more information on the Device Flow visit: - - https://docs.github.com/apps/creating-github-apps/writing-code-for-a-github-app/building-a-cli-with-a-github-app - - For information about scopes and other authentication methods on GitHub: - - https://docs.github.com/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps - - https://docs.github.com/rest/overview/other-authentication-methods#authenticating-for-saml-sso diff --git a/src/en-US/about_Config.help.txt b/src/en-US/about_Config.help.txt deleted file mode 100644 index d6e25c783..000000000 --- a/src/en-US/about_Config.help.txt +++ /dev/null @@ -1,107 +0,0 @@ -TOPIC - about_Config - -SHORT DESCRIPTION - Provides details about the configuration management functions in the PowerShell Module. - -LONG DESCRIPTION - The PowerShell Module provides a set of functions to manage the configuration related to the module. - The configuration is stored in a secret vault and can be accessed, modified, saved, and restored - using the provided cmdlets. - -DATA STRUCTURE - - Name: SecretVault - Purpose: Hold static configuration data about the secret vault. - Path: \classes\Data\SecretVault.psd1 - - | Name | Type | Static Value | Description | - | ---------------------------- | -------------- | ---------------------------------- | ----------------------------- | - | SecretVault | pscustomobject | {Name, Type, Secret} | | - | SecretVault.Name | string | 'GitHub' | The name of the secret vault. | - | SecretVault.Type | string | 'Microsoft.PowerShell.SecretStore' | The type of the secret vault. | - | SecretVault.Secret | pscustomobject | {Name} | | - | SecretVault.Secret.Name | string | 'Config' | The name of the secret. | - - Name: Config - Purpose: Hold the current configuration data. - Path: \classes\Data\Config.ps1 - - | Name | Type | Default Value | Description | - | ------------------------------------ | -------------- | ------------------------ | --------------------------------- | - | App | pscustomobject | | | - | App.API | pscustomobject | | | - | App.API.BaseURI | string | 'https://api.github.com' | The GitHub API Base URI. | - | App.API.Version | string | '2022-11-28' | The GitHub API version. | - | App.Defaults | pscustomobject | {} | | - | User | pscustomobject | | | - | User.Auth | pscustomobject | | | - | User.Auth.AccessToken | pscustomobject | | The access token. | - | User.Auth.AccessToken.Value | string | '' | The access token value. | - | User.Auth.AccessToken.ExpirationDate | datetime | [datetime]::MinValue | The access token expiration date. | - | User.Auth.ClientID | string | '' | The client ID. | - | User.Auth.Mode | string | '' | The authentication mode. | - | User.Auth.RefreshToken | pscustomobject | | The refresh token. | - | User.Auth.RefreshToken.Value | string | '' | The refresh token value. | - | User.Auth.RefreshToken.ExpirationDate| datetime | [datetime]::MinValue | The refresh token expiration date.| - | User.Auth.Scope | string | '' | The scope. | - | User.Defaults | pscustomobject | | | - | User.Defaults.Owner | string | '' | The default owner. | - | User.Defaults.Repo | string | '' | The default repository. | - -FUNCTIONS - - - Get-GitHubConfig: Fetches the current module configuration. - - Reset-GitHubConfig: Resets all or specific sections to its default values. - - Set-GitHubConfig: Allows setting specific elements of the configuration. - -CONFIGURATION - - The configuration values are securely stored using the SecretManagement and SecretStore modules. During the module import, the following steps are performed: - - 1. Initialize the configuration store. - - Check for secret vault of type 'Microsoft.PowerShell.SecretStore'. - If not registered for the current user, its configuration will be reset to unattended mode. - - Check for secret vault with the name 'GitHub'. - If it does not exist, it will be created with current configuration. - If the user is already using the secret vault, the existing configuration will be kept. - 2. Restore saved configuration from the configuration store. - - Look for the 'GitHub' secret vault. - - Look for the secret called 'Config'. If it exists, restore the configuration from it into memory. - -EXAMPLES - - -------------------------- EXAMPLE 1 -------------------------- - - Get-GitHubConfig - - This command retrieves the current GitHub configuration. - - -------------------------- EXAMPLE 2 -------------------------- - - Set-GitHubConfig -APIBaseURI 'https://api.newurl.com' -APIVersion '2023-09-23' - - This command sets the API Base URI to 'https://api.newurl.com' and the API version to '2023-09-23'. - - -------------------------- EXAMPLE 3 -------------------------- - - Reset-GitHubConfig -Scope Auth - - This command resets the Auth related settings of the GitHub configuration to its default values. - - -KEYWORDS - - GitHub - PowerShell - SecretManagement - SecretStore - -SEE ALSO - - - For more information about SecretManagement and SecretStore: - https://learn.microsoft.com/en-us/powershell/utility-modules/secretmanagement/overview?view=ps-modules - - The GitHub repository of this module: - https://github.com/PSModule/GitHub - - PowerShell Gallery page for SecretManagement module: - https://www.powershellgallery.com/packages/Microsoft.PowerShell.SecretManagement/ From ad730faefa08cfbc9cfe60cfdbc50ad46a0ae232 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 6 Nov 2024 12:32:32 +0100 Subject: [PATCH 2/7] Clean out dumped code as it is implemented --- .../New-GitHubAppInstallationAccessToken.ps1 | 264 ------------------ 1 file changed, 264 deletions(-) delete mode 100644 tools/dev/New-GitHubAppInstallationAccessToken.ps1 diff --git a/tools/dev/New-GitHubAppInstallationAccessToken.ps1 b/tools/dev/New-GitHubAppInstallationAccessToken.ps1 deleted file mode 100644 index 717af28ca..000000000 --- a/tools/dev/New-GitHubAppInstallationAccessToken.ps1 +++ /dev/null @@ -1,264 +0,0 @@ -#Create an installation access token for an app - -<# -Path parameters -Name, Type, Description -installation_id integer Required -The unique identifier of the installation. - -Body parameters -Name, Type, Description -repositories array of strings -List of repository names that the token should have access to - -repository_ids array of integers -List of repository IDs that the token should have access to - -permissions object -The permissions granted to the user access token. - -Properties of permissions -Name, Type, Description -actions string -The level of permission to grant the access token for GitHub Actions workflows, workflow runs, and artifacts. - -Can be one of: read, write - -administration string -The level of permission to grant the access token for repository creation, deletion, settings, teams, and collaborators creation. - -Can be one of: read, write - -checks string -The level of permission to grant the access token for checks on code. - -Can be one of: read, write - -codespaces string -The level of permission to grant the access token to create, edit, delete, and list Codespaces. - -Can be one of: read, write - -contents string -The level of permission to grant the access token for repository contents, commits, branches, downloads, releases, and merges. - -Can be one of: read, write - -dependabot_secrets string -The leve of permission to grant the access token to manage Dependabot secrets. - -Can be one of: read, write - -deployments string -The level of permission to grant the access token for deployments and deployment statuses. - -Can be one of: read, write - -environments string -The level of permission to grant the access token for managing repository environments. - -Can be one of: read, write - -issues string -The level of permission to grant the access token for issues and related comments, assignees, labels, and milestones. - -Can be one of: read, write - -metadata string -The level of permission to grant the access token to search repositories, list collaborators, and access repository metadata. - -Can be one of: read, write - -packages string -The level of permission to grant the access token for packages published to GitHub Packages. - -Can be one of: read, write - -pages string -The level of permission to grant the access token to retrieve Pages statuses, configuration, and builds, as well as create new builds. - -Can be one of: read, write - -pull_requests string -The level of permission to grant the access token for pull requests and related comments, assignees, labels, milestones, and merges. - -Can be one of: read, write - -repository_custom_properties string -The level of permission to grant the access token to view and edit custom properties for a repository, when allowed by the property. - -Can be one of: read, write - -repository_hooks string -The level of permission to grant the access token to manage the post-receive hooks for a repository. - -Can be one of: read, write - -repository_projects string -The level of permission to grant the access token to manage repository projects, columns, and cards. - -Can be one of: read, write, admin - -secret_scanning_alerts string -The level of permission to grant the access token to view and manage secret scanning alerts. - -Can be one of: read, write - -secrets string -The level of permission to grant the access token to manage repository secrets. - -Can be one of: read, write - -security_events string -The level of permission to grant the access token to view and manage security events like code scanning alerts. - -Can be one of: read, write - -single_file string -The level of permission to grant the access token to manage just a single file. - -Can be one of: read, write - -statuses string -The level of permission to grant the access token for commit statuses. - -Can be one of: read, write - -vulnerability_alerts string -The level of permission to grant the access token to manage Dependabot alerts. - -Can be one of: read, write - -workflows string -The level of permission to grant the access token to update GitHub Actions workflow files. - -Value: write - -members string -The level of permission to grant the access token for organization teams and members. - -Can be one of: read, write - -organization_administration string -The level of permission to grant the access token to manage access to an organization. - -Can be one of: read, write - -organization_custom_roles string -The level of permission to grant the access token for custom repository roles management. - -Can be one of: read, write - -organization_custom_org_roles string -The level of permission to grant the access token for custom organization roles management. - -Can be one of: read, write - -organization_custom_properties string -The level of permission to grant the access token for custom property management. - -Can be one of: read, write, admin - -organization_copilot_seat_management string -The level of permission to grant the access token for managing access to GitHub Copilot for members of an organization with a Copilot Business subscription. This property is in beta and is subject to change. - -Value: write - -organization_announcement_banners string -The level of permission to grant the access token to view and manage announcement banners for an organization. - -Can be one of: read, write - -organization_events string -The level of permission to grant the access token to view events triggered by an activity in an organization. - -Value: read - -organization_hooks string -The level of permission to grant the access token to manage the post-receive hooks for an organization. - -Can be one of: read, write - -organization_personal_access_tokens string -The level of permission to grant the access token for viewing and managing fine-grained personal access token requests to an organization. - -Can be one of: read, write - -organization_personal_access_token_requests string -The level of permission to grant the access token for viewing and managing fine-grained personal access tokens that have been approved by an organization. - -Can be one of: read, write - -organization_plan string -The level of permission to grant the access token for viewing an organization's plan. - -Value: read - -organization_projects string -The level of permission to grant the access token to manage organization projects and projects beta (where available). - -Can be one of: read, write, admin - -organization_packages string -The level of permission to grant the access token for organization packages published to GitHub Packages. - -Can be one of: read, write - -organization_secrets string -The level of permission to grant the access token to manage organization secrets. - -Can be one of: read, write - -organization_self_hosted_runners string -The level of permission to grant the access token to view and manage GitHub Actions self-hosted runners available to an organization. - -Can be one of: read, write - -organization_user_blocking string -The level of permission to grant the access token to view and manage users blocked by the organization. - -Can be one of: read, write - -team_discussions string -The level of permission to grant the access token to manage team discussions and related comments. - -Can be one of: read, write - -email_addresses string -The level of permission to grant the access token to manage the email addresses belonging to a user. - -Can be one of: read, write - -followers string -The level of permission to grant the access token to manage the followers belonging to a user. - -Can be one of: read, write - -git_ssh_keys string -The level of permission to grant the access token to manage git SSH keys. - -Can be one of: read, write - -gpg_keys string -The level of permission to grant the access token to view and manage GPG keys belonging to a user. - -Can be one of: read, write - -interaction_limits string -The level of permission to grant the access token to view and manage interaction limits on a repository. - -Can be one of: read, write - -profile string -The level of permission to grant the access token to manage the profile settings belonging to a user. - -Value: write - -starring string -The level of permission to grant the access token to list and manage repositories a user is starring. - -Can be one of: read, write -#> -Invoke-RestMethod -Uri 'https://api.github.com/app/installations/53353776/access_tokens' -Headers @{ - Authorization = "Bearer $token" -} -Method POST From 39a6606b1e0011889fad8400b91d6d8c42087174 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 6 Nov 2024 12:32:48 +0100 Subject: [PATCH 3/7] cleanup user journey example file --- tools/dev/UserJourney.ps1 | 60 ++++++++++++++++----------------------- 1 file changed, 25 insertions(+), 35 deletions(-) diff --git a/tools/dev/UserJourney.ps1 b/tools/dev/UserJourney.ps1 index ac66ee0fa..db74da564 100644 --- a/tools/dev/UserJourney.ps1 +++ b/tools/dev/UserJourney.ps1 @@ -2,26 +2,6 @@ ### CONNECTING ### -# When you connect, a context is saved. -# Variables, stored under "Contexts" on the existing config.json. -# Secrets, names are stored in the variables. -# Context = [ -# { -# name: "github.com/MariusStorhaug" -# id: 1 -# host: "github.com" -# default: true -# type: UAT -# }, -# { -# name: "dnb.ghe.com/Marius-Storhaug" -# id: 2 -# host: "dnb.ghe.com" -# default: false -# type: UAT -# } -# ] - # Connect to GitHub interactively using GitHub App and Device Flow (User Access Token, UAT) Connect-GitHub (-Host github.com) (-ClientID '') @@ -43,26 +23,36 @@ Connect-GitHub -ClientID '' -PrivateKey '' # Connect to GitHub programatically (GitHub App Installation Access Token) Connect-GitHub -Token *********** + ### -### ADVANCED CONNECTING +### Contexts / Profiles ### -# Bring you own GitHub App -Set-GitHubAuthApp -ClientID '' -Check-GitHubAuthApp -Connect-GitHub - - - - - -# What about profiles? -Get-GitHubContext # List all contexts -Get-GitHubContext -Context 'name' # Returns a specific context +# When you connect, a context is saved. +# Variables, stored under "Contexts" on the existing config.json. +# Secrets, names are stored in the variables. +# Context = [ +# { +# name: "github.com/MariusStorhaug" +# id: 1 +# host: "github.com" +# default: true +# type: UAT +# }, +# { +# name: "dnb.ghe.com/Marius-Storhaug" +# id: 2 +# host: "dnb.ghe.com" +# default: false +# type: UAT +# } +# ] +Get-GitHubContext # List all contexts -> Get-GitHubConfig? +Get-GitHubContext -Context 'name' # Returns a specific context, autocomplete the name. -Set-GitHubContext -Context 'name' # Take a name? Autocomplete the name +Set-GitHubContext -Context 'name' # Take a name dynamically from Get-GitHubContext? Autocomplete the name -Disconnect-GitHub -Context 'name' +Disconnect-GitHub -Context 'name' # Removes the context variables and secrets # Calling specific functions with context or an ad-hoc token? From 8b6a22a89b9ce6681f66213464c4a60a7476ce71 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 6 Nov 2024 12:33:30 +0100 Subject: [PATCH 4/7] Cleanup commented code in Get-GitHubAppInstallations.ps1 --- tools/dev/Get-GitHubAppInstallations.ps1 | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/tools/dev/Get-GitHubAppInstallations.ps1 b/tools/dev/Get-GitHubAppInstallations.ps1 index 56a6b74f2..232917ef1 100644 --- a/tools/dev/Get-GitHubAppInstallations.ps1 +++ b/tools/dev/Get-GitHubAppInstallations.ps1 @@ -1,8 +1,9 @@  -#List installations for the authenticated app -Invoke-RestMethod -Uri 'https://api.github.com/app/installations' -Headers @{ - Authorization = "Bearer $token" -} +# #List installations for the authenticated app +# Implemented... +# Invoke-RestMethod -Uri 'https://api.github.com/app/installations' -Headers @{ +# Authorization = "Bearer $token" +# } #Get an organization installation for the authenticated app From e2c1e4e47ebe3bb472c340bbb3f84006d193db25 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 6 Nov 2024 13:27:35 +0100 Subject: [PATCH 5/7] Cleanup documentation --- README.md | 32 ++++++++++++++++++++++++++++---- tools/dev/dump.ps1 | 24 ------------------------ 2 files changed, 28 insertions(+), 28 deletions(-) delete mode 100644 tools/dev/dump.ps1 diff --git a/README.md b/README.md index 70b304590..1d11ee721 100644 --- a/README.md +++ b/README.md @@ -27,14 +27,12 @@ To dive into the world of GitHub automation with PowerShell, follow the sections Download and install the GitHub PowerShell module from the PowerShell Gallery with the following command: ```powershell -Install-Module -Name GitHub -Force -AllowClobber +Install-PSResource -Name GitHub -Repository PSGallery -TrustRepository ``` ### Logging on -Authenticate using your GitHub credentials or access tokens to begin executing commands. Tokens and other -configuration details are stored encrypted on the system using the PowerShell modules [SecretManagement and SecretStore Overview](https://learn.microsoft.com/en-us/powershell/utility-modules/secretmanagement/overview?view=ps-modules), -for more info on the implementation, see the section on storing configuration. +Authenticate using your GitHub credentials or access tokens to begin executing commands. The module supports multiple authentication methods. #### Device flow @@ -107,6 +105,32 @@ Connect-GitHubAccount ✓ Logged in as system! ``` +#### Using a GitHub App + +If you are using a GitHub App, you can use the `Connect-GitHubApp` command to authenticate using the cliend id and private key. + +```powershell +Connect-GitHubApp -ClientId 'lv123456789' -PrivateKey '-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----' +✓ Logged in as my-github-app! +``` + +#### Using a different host + +If you are using GitHub Enterprise, you can use the `-Host` 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! +``` + ### Command Exploration Familiarize yourself with the available cmdlets using the module's comprehensive documentation or inline help. diff --git a/tools/dev/dump.ps1 b/tools/dev/dump.ps1 deleted file mode 100644 index c45d2cde2..000000000 --- a/tools/dev/dump.ps1 +++ /dev/null @@ -1,24 +0,0 @@ - - -function Get-GitHubRepository { - [CmdletBinding()] - param ( - [Parameter(Mandatory)] - [string] $OrganizationName, - - [Parameter(Mandatory)] - [string] $Token, - - [Parameter()] - $BaseURL = $env:GITHUB_API_URL - ) - - $result = Invoke-RestMethod -Method Get -Uri "$BaseURL/orgs/$OrganizationName/repos" -Headers @{ - 'Authorization' = "Bearer $token" - 'Accept' = 'application/vnd.github+json' - } -FollowRelLink - - $result | ForEach-Object { - Write-Output $_ - } -} From 444c7ba980f0a39d4d5d3b097e972c019539ce2b Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 6 Nov 2024 13:29:21 +0100 Subject: [PATCH 6/7] typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1d11ee721..2f969d42c 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,7 @@ Connect-GitHubAccount #### Using a GitHub App -If you are using a GitHub App, you can use the `Connect-GitHubApp` command to authenticate using the cliend id and private key. +If you are using a GitHub App, you can use the `Connect-GitHubApp` command to authenticate using the client id and private key. ```powershell Connect-GitHubApp -ClientId 'lv123456789' -PrivateKey '-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----' From ca2188751059987843624f0d1fcac307b3db97aa Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 6 Nov 2024 13:46:38 +0100 Subject: [PATCH 7/7] fix --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2f969d42c..bd37a056a 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,7 @@ Connect-GitHubAccount #### Using a GitHub App -If you are using a GitHub App, you can use the `Connect-GitHubApp` command to authenticate using the client id and private key. +If you are using a GitHub App, you can use the `Connect-GitHubApp` command to authenticate using the client ID and private key. ```powershell Connect-GitHubApp -ClientId 'lv123456789' -PrivateKey '-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----'