Home

Awesome

PSGitHub

powershellgallery downloads build chat

PowerShell module with commands to query and manage GitHub through its REST API.

Installation

Install PSGitHub

You can install the PSGitHub PowerShell module using one of the following methods.

  1. Install from the PowerShell Gallery (requires PowerShell 5.0+) 
    Install-Module PSGitHub
  2. Copy-install the module to your $env:PSModulePath
  3. Extract the module anywhere on the filesystem, and import it explicitly, using Import-Module

Setup

To access private repositories, make changes and have a higher rate limit, create a GitHub token. This token can be provided to all PSGitHub functions as a SecureString through the -Token parameter. You can set a default token to be used by changing $PSDefaultParameterValues in your profile.ps1:

On Windows

$PSDefaultParameterValues['*GitHub*:Token'] = 'YOUR_ENCRYPTED_TOKEN' | ConvertTo-SecureString

To get the value for YOUR_ENCRYPTED_TOKEN, run Read-Host -AsSecureString | ConvertFrom-SecureString once and paste in your token.

On macOS/Linux

macOS and Linux do not have access to the Windows Data Protection API, so they cannot use ConvertFrom-SecureString to generate an encrypted plaintext version of the token without a custom encryption key.

If you are not concerned about storing the token in plain text in the profile.ps1, you can set it like this:

$PSDefaultParameterValues['*GitHub*:Token'] = 'YOUR_PLAINTEXT_TOKEN' | ConvertTo-SecureString -AsPlainText -Force

Alternatively, you could store the token in a password manager or the Keychain, then retrieve it in your profile and set it the same way.

Features

Included Cmdlets

<!-- Generate rows with Get-Command -Name *-GitHub* -CommandType Function | Group-Object -Property { ($_.Name -split '-')[1] } | ForEach-Object { "| $(($_.Group | ForEach-Object { ($_.Name -split '-')[0] }) -join ', ') | $($_.Name -replace 'GitHub','') |" } -->
Supported VerbsGitHub Resource
Add, GetAssignee
GetCombinedCommitStatus
Get, NewComment
StartFork
Get, New, Remove, Save, UpdateGist
RemoveGitRef
Find, Get, New, UpdateIssue
GetIssueTimeline
Find, Get, New, Remove, UpdateLabel
GetLicense
GetMilestone
GetOrganization
GetProject
Get, Move, NewProjectCard
GetProjectColumn
Get, Merge, NewPullRequest
GetPullRequestFile
GetRateLimit
Get, NewRelease
Get, New, RemoveReleaseAsset
Find, Get, New, RemoveRepository
New, SubmitReview
NewReviewRequest
GetTeam
GetTeamMember
SetToken
Find, Get, UpdateUser

Pretty Formatting

PSGitHub includes pretty, colored output formatting. Different views are available when piping to different Format-* cmdlets (Format-Table, Format-List, Format-Custom and Format-Wide) and specifying the -View parameter. Markdown in issue bodies and comments is highlighted as well.

Issues & Pull Requests

Format-Table (default)

Screenshot of Issue Table View

Format-Custom

Screenshot of Issue Custom View

Format-List -View Full

Includes colored labels and rendered markdown.

Screenshot of PullRequest List Full View

Milestones

Screenshot of Milestone Table View

Labels

Screenshot of Label Table View

Labels also support Format-Wide.

Commit Statuses

Screenshot of CombinedCommitStatus List View

Autocompletion

There is autocompletion for almost all parameters, namely -Owner, -RepositoryName, -Number (issue numbers), -Label, -Assignee, -MilestoneName. Search keywords in Find-Github* queries also have autocompletion.

Screenshot of issue autocompletion

Pipeline Support

All cmdlets have pipeline support. This means you can take the output of one cmdlet like Find-GitHubIssue and pipe it into another like Update-GitHubIssue.

# Close all wont-fix issues
Find-GitHubIssue "is:open label:wont-fix" | Update-GitHubIssue -State closed

PSGitHub is also designed to interoperate with PowerGit. This means for example that you can pipe a PowerGit branch object into New-GitHubPullRequest to open a new pull request from that branch (Get-GitHubPullRequest and Merge-GitHubPullRequest work equally). At the minimum, piping any PowerGit object (repository, branch, commit, remote, etc) will fill the -Owner and -RepositoryName parameters.

# Opening a new PR for a new branch
New-GitBranch my-branch | Send-GitObject | New-GitHubPullRequest

# Merging the PR of the current branch
Get-GitHead | Merge-GitHubPullRequest -WaitForStatusChecks

# Clone a GitHub repository
Get-GitHubRepository -RepositoryName foo | Copy-GitRepository

Pagination

Pagination is automatic. Every cmdlet that queries collections will keep making requests for new pages and emit objects until the end is reached. To limit the number of results, pipe to Select-Object -First.

Types

All objects returned are raw GitHub API responses, however with assigned TypeNames, which have Types.ps1xml files. They are extended with several additional properties, for example aliasing all snake_cased properties to PascalCase for consistency with PowerShell naming conventions.

Contributing

SVG Screenshots

SVG Screenshots are created with term2svg

termtosvg ./Screenshots/frames -s -g 100x12 -t base16_default_dark -c 'pwsh -NoExit -Command clear'

-s outputs still .svg frames. Always use the base16_default_dark theme for consistency. Keep the column width at 100 for best readability in the README (resize your terminal to match the width). If 12 is not enough the row height should be matched to the output of the command. Execute your command, then execute exit. Pick the frame that shows the command output but does not show the next prompt.

Issues

Please report issues in the GitHub Issue Tracker.

Contributors

This module was originally developed by Trevor Sullivan. You can contact Trevor using one of the following methods:

Core Contributors