Skip to content

Latest commit

 

History

History
1407 lines (1071 loc) · 47.2 KB

USAGE.md

File metadata and controls

1407 lines (1071 loc) · 47.2 KB
Raw

PowerShellForGitHub PowerShell Module

Usage

Table of Contents

Full Module Documentation

All commands for the module have "Comment-Based Help" available at your fingertips. You can access that help at any time by running:

Get-Help -Full <commandName>

In addition to accessing it from the commandline, all of that help documentation is also available online on our wiki.

Logging

All commands will log to the console, as well as to a log file, by default. The logging is affected by configuration properties (which can be checked with Get-GitHubConfiguration and changed with Set-GitHubConfiguration).

LogPath [string] The logfile. Defaults to ([System.Environment]::GetFolderPath('MyDocuments'))\PowerShellForGitHub.log. Will default to ([System.Environment]::GetFolderPath('LocalApplicationData'))\PowerShellForGitHub.log when there is no user profile (like in an Azure environment).

DisableLogging [bool] Defaults to $false.

LogTimeAsUtc [bool] Defaults to $false. If $false, times are logged in local time. When $true, times are logged using UTC (and those timestamps will end with a Z per the W3C standard)

LogProcessId [bool] Defaults to $false. If $true, the Process ID ($global:PID) of the current PowerShell process will be added to every log entry. This can be helpful if you have situations where multiple instances of this module run concurrently and you want to more easily isolate the log entries for one process. An alternative solution would be to use Set-GitHubConfiguration -LogPath <path> -SessionOnly to specify a different log file for each PowerShell process. An easy way to view the filtered entries for a session is (replacing PID with the PID that you are interested in):

Get-Content -Path <logPath> -Encoding UTF8 | Where { $_ -like '*[[]PID[]]*' }

Telemetry

In order to track usage, gauge performance and identify areas for improvement, telemetry is employed during execution of commands within this module (via Application Insights). For more information, refer to the Privacy Policy.

We recommend that you always leave the telemetry feature enabled, but a situation may arise where it must be disabled for some reason. In this scenario, you can disable telemetry by calling:

Set-GitHubConfiguration -DisableTelemetry -SessionOnly

The effect of that value will last for the duration of your session (until you close your console window). To make that change permanent, remove -SessionOnly from that call.

The following type of information is collected:

  • Every major command executed (to gauge usefulness of the various commands)
  • Types of parameters used with the command
  • Error codes / information

The following information is also collected, but the reported information is only reported in the form of an SHA512 Hash (to protect PII (personal identifiable information)):

  • Username
  • OwnerName
  • RepositoryName
  • OrganizationName

The hashing of the above items can be disabled (meaning that the plaint-text data will be reported instead of the hash of the data) by setting

Set-GitHubConfiguration -DisablePiiProtection -SessionOnly

Similar to DisableTelemetry, the effect of this value will only last for the duration of your session (until you close your console window), unless you call it without -SessionOnly.

The first time telemetry is tracked in a new PowerShell session, a reminder message will be displayed to the user. To suppress this reminder in the future, call:

Set-GitHubConfiguration -SuppressTelemetryReminder

Finally, the Application Insights Key that the telemetry is reported to is exposed as

Get-GitHubConfiguration -Name ApplicationInsightsKey

It is requested that you do not change this value, otherwise the telemetry will not be reported to us for analysis. We expose it here for complete transparency.

Common PowerShell API Patterns

This module adopts many of the standard PowerShell API design patterns. We want to call attention to those patterns here so that you can identify how you can most efficiently use the module.

Confirmation Required for Major Actions

All commands that result in removing/deleting an object, as well as some commands that rename objects (like renaming a repository) require user confirmation before the comamnd will be processed. You can avoid that user confirmation by passing in either -Confirm:$false or -Force.

WhatIf Supported for All State Changing Commands

Any command that isn't Get-GitHub* supports the -WhatIf switch. You can safely call that command by passing in the -WhatIf switch and know that the request will not actually be sent to GitHub. This can be useful when paired with the -Verbose switch if you are examining what is happening behind the scenes.

State Changing Commands are Silent by Default

By default, state changing commands like Set-*, Rename-*, etc... will not produce any output unless you specify the -PassThru switch. You can change that default behavior by calling

Set-GitHubConfiguration -DefaultPassThru:$true

Examples

Overview

Embracing the Pipeline

One of the major benefits of PowerShell is its pipeline -- allowing you to "pipe" a saved value or the output of a previous command directly into the next command. There is absolutely no requirement to make use of it in order to use the module, but you will find that the module becomes increasingly easier to use and more powerful if you do.

Some of the examples that you find below will show how you might be able to use it to your advantage.

Pipeline Example

Most commands require you to pass in either a Uri for the repository or its elements (the OwnerName and RepositoryName). If you keep around the repo that you're interacting with in a local var (like $repo), then you can pipe that into any command to avoid having to specify that information. Further, piping in a more specific object (like an Issue) allows you to avoid even specifying the relevant Issue number.

Without the pipeline, an interaction log might look like this:

# Find all of the issues that have the label "repro steps needed" and add a new comment to those
# issues asking for an update.
$issues = @(Get-GitHubIssue -OwnerName microsoft -RepositoryName PowerShellForGitHub -Label 'repro steps needed')
foreach ($issue in $issues)
{
    $params = @{
        'OwnerName' = 'microsoft'
        'RepositoryName' = 'PowerShellForGitHub'
        'Issue' = $issue.number
        'Body' = 'Any update on those repro steps?'
    }

    New-GitHubIssueComment @params
}

With the pipeline, a similar interaction log might look like this:

# Find all of the issues that have the label "repro steps needed" and add a new comment to those
# issues asking for an update.
Get-GitHubRepository -OwnerName microsoft -RepositoryName PowerShellForGitHub |
    Get-GitHubIssue -Label 'repro steps needed' |
    New-GitHubIssueComment -Body 'Any update on those repro steps?'

We encourage you to explore how embracing the pipeline may simplify your code and interaction with GitHub using this module!

Analytics

Querying Issues

# Getting all of the issues from the PowerShell\xPSDesiredStateConfiguration repository
$issues = Get-GitHubIssue -OwnerName PowerShell -RepositoryName 'xPSDesiredStateConfiguration'
# An example of accomplishing what Get-GitHubIssueForRepository (from v0.1.0) used to do.
# Get all of the issues from multiple repos, but only return back the ones that were created within
# past two weeks.
$repos = @('https://github.com/powershell/xpsdesiredstateconfiguration', 'https://github.com/powershell/xactivedirectory')
$issues = @()
$repos | ForEach-Object { $issues += Get-GitHubIssue -Uri $_ }
$issues | Where-Object { $_.created_at -gt (Get-Date).AddDays(-14) }
# An example of accomplishing what Get-GitHubWeeklyIssueForRepository (from v0.1.0) used to do.
# Get all of the issues from multiple repos, and group them by the week in which they were created.
$repos = @('https://github.com/powershell/xpsdesiredstateconfiguration', 'https://github.com/powershell/xactivedirectory')
$issues = @()
$repos | ForEach-Object { $issues += Get-GitHubIssue -Uri $_ }
$issues | Group-GitHubIssue -Weeks 12 -DateType Created
# An example of accomplishing what Get-GitHubTopIssueRepository (from v0.1.0) used to do.
# Get all of the issues from multiple repos, and sort the repos by the number issues that they have.
$repos = @('https://github.com/powershell/xpsdesiredstateconfiguration', 'https://github.com/powershell/xactivedirectory')
$issueCounts = @()
$issueSearchParams = @{
    'State' = 'open'
}
$repos | ForEach-Object { $issueCounts += ([PSCustomObject]@{ 'Uri' = $_; 'Count' = (Get-GitHubIssue -Uri $_ @issueSearchParams).Count }) }
$issueCounts | Sort-Object -Property Count -Descending

Querying Pull Requests

# Getting all of the pull requests from the microsoft\PowerShellForGitHub repository
$issues = Get-GitHubIssue -OwnerName microsoft -RepositoryName 'PowerShellForGitHub'
# An example of accomplishing what Get-GitHubPullRequestForRepository (from v0.1.0) used to do.
# Get all of the pull requests from multiple repos, but only return back the ones that were created
# within the past two weeks.
$repos = @('https://github.com/powershell/xpsdesiredstateconfiguration', 'https://github.com/powershell/xactivedirectory')
$pullRequests = @()
$repos | ForEach-Object { $pullRequests += Get-GitHubPullRequest -Uri $_ }
$pullRequests | Where-Object { $_.created_at -gt (Get-Date).AddDays(-14) }
# An example of accomplishing what Get-GitHubWeeklyPullRequestForRepository (from v0.1.0) used to do.
# Get all of the pull requests from multiple repos, and group them by the week in which they were merged.
$repos = @('https://github.com/powershell/xpsdesiredstateconfiguration', 'https://github.com/powershell/xactivedirectory')
$pullRequests = @()
$repos | ForEach-Object { $pullRequests += Get-GitHubPullRequest -Uri $_ }
$pullRequests | Group-GitHubPullRequest -Weeks 12 -DateType Merged
# An example of accomplishing what Get-GitHubTopPullRequestRepository (from v0.1.0) used to do.
# Get all of the pull requests from multiple repos, and sort the repos by the number
# of closed pull requests that they have had within the past two weeks.
$repos = @('https://github.com/powershell/xpsdesiredstateconfiguration', 'https://github.com/powershell/xactivedirectory')
$pullRequestCounts = @()
$pullRequestSearchParams = @{
    'State' = 'closed'
}
$repos |
    ForEach-Object {
        $pullRequestCounts += ([PSCustomObject]@{
            'Uri' = $_;
            'Count' = (
                (Get-GitHubPullRequest -Uri $_ @pullRequestSearchParams) |
                    Where-Object { $_.completed_at -gt (Get-Date).AddDays(-14) }
            ).Count
        }) }

$pullRequestCounts | Sort-Object -Property Count -Descending

Querying Collaborators

$collaborators = Get-GitHubRepositoryCollaborators`
    -Uri @('https://github.com/PowerShell/DscResources')

Querying Contributors

# Getting all of the contributors for a single repository
$contributors = Get-GitHubRepositoryContributor -OwnerName 'PowerShell' -RepositoryName 'PowerShellForGitHub' }
# An example of accomplishing what Get-GitHubRepositoryContributors (from v0.1.0) used to do.
# Getting all of the contributors for a set of repositories
$repos = @('https://github.com/PowerShell/DscResources', 'https://github.com/PowerShell/xWebAdministration')
$contributors = @()
$repos | ForEach-Object { $contributors += Get-GitHubRepositoryContributor -Uri $_ }
# An example of accomplishing what Get-GitHubRepositoryUniqueContributor (from v0.1.0) used to do.
# Getting the unique set of contributors from the previous results of Get-GitHubRepositoryContributor
Get-GitHubRepositoryContributor -OwnerName 'PowerShell' -RepositoryName 'PowerShellForGitHub' } |
    Select-Object -ExpandProperty author |
    Select-Object -ExpandProperty login -Unique
    Sort-Object

Querying Team and Organization Membership

$organizationMembers = Get-GitHubOrganizationMember -OrganizationName 'OrganizationName'
$teamMembers = Get-GitHubTeamMember -OrganizationName 'OrganizationName' -TeamName 'TeamName'

Labels

Getting Labels for a Repository

$labels = Get-GitHubLabel -OwnerName PowerShell -RepositoryName DesiredStateConfiguration

Getting Labels for an Issue

$labels = Get-GitHubLabel -OwnerName PowerShell -RepositoryName DesiredStateConfiguration -Issue 1

Getting Labels for a Milestone

$labels = Get-GitHubLabel -OwnerName PowerShell -RepositoryName DesiredStateConfiguration -Milestone 1

Adding a New Label to a Repository

New-GitHubLabel -OwnerName PowerShell -RepositoryName DesiredStateConfiguration -Name TestLabel -Color BBBBBB

Removing a Label From a Repository

Remove-GitHubLabel -OwnerName PowerShell -RepositoryName DesiredStateConfiguration -Name TestLabel

Adding Labels to an Issue

$labelNames = @('bug', 'discussion')
Add-GitHubIssueLabel -OwnerName $script:ownerName -RepositoryName $repositoryName -Issue 1 -LabelName $labelNames

Removing a Label From an Issue

Remove-GitHubIssueLabel -OwnerName microsoft -RepositoryName DesiredStateConfiguration -Name TestLabel -Issue 1

Updating a Label With a New Name and Color

Set-GitHubLabel -OwnerName microsoft -RepositoryName DesiredStateConfiguration -Name TestLabel -NewName NewTestLabel -Color BBBB00

Bulk Updating Labels in a Repository

This replaces the entire set of labels in a repository to only contain the labels in the provided array. Any labels already in the repository that are not in this array will be removed upon execution.

$labels = @( @{ 'name' = 'Label1'; 'color' = 'BBBB00'; 'description' = 'My label description' }, @{ 'name' = 'Label2'; 'color' = 'FF00000' })
Initialize-GitHubLabel -OwnerName PowerShell -RepositoryName DesiredStateConfiguration -Label $labels

Users

Getting the current authenticated user

Get-GitHubUser -Current

Updating the current authenticated user's profile

Set-GitHubProfile -Location 'Seattle, WA' -Hireable:$false

Getting any user

Get-GitHubUser -UserName octocat

Getting all users

Get-GitHubUser

Warning: This will take a while. It's getting every GitHub user.

Repositories

Adding a new Branch to a Repository

New-GitHubRepositoryBranch -OwnerName microsoft -RepositoryName PowerShellForGitHub -Name develop

Removing a Branch from a Repository

Remove-GitHubRepositoryBranch -OwnerName microsoft -RepositoryName PowerShellForGitHub -Name develop

Teams

Getting teams in an Organization

Get-GitHubTeam -OrganizationName microsoft

Getting teams assigned to a repository

Get-GitHubTeam -OwnerName microsoft -RepositoryName PowerShellForGitHub

Getting a team by team name

Get-GitHubTeam -OrganizationName microsoft -TeamName MyTeam

Getting a team by team id

Get-GitHubTeam -OrganizationName microsoft -TeamId 378661

Creating a team

New-GitHubTeam -OrganizationName microsoft -TeamName MyTeam -Description 'Team Description'

Creating a child team

New-GitHubTeam -OrganizationName microsoft -TeamName MyChildTeam -Description 'Team Description' -ParentTeamName MyTeam

Updating a team

Update-GitHubTeam -OrganizationName microsoft -TeamName MyChildTeam -Description 'Team Description' -ParentTeamName MyTeam

Removing a team

Remove-GitHubTeam -OrganizationName microsoft -TeamName MyTeam

Repositories

Create a repository

New-GitHubRepository -RepositoryName TestRepo

Create a repository in an organization

New-GitHubRepository -RepositoryName TestRepo -OrganizationName MyOrg

Create a repository in an organization and grant access to a team

$myTeam = Get-GitHubTeam -OrganizationName MyOrg | Where-Object -Property name -eq MyTeam
New-GitHubRepository -RepositoryName TestRepo -OrganizationName MyOrg -TeamId $myTeam.id

Create a repository from a template repository

New-GitHubRepositoryFromTemplate -OwnerName MyOrg -RepositoryName TemplateRepoName -TargetRepositoryName MyNewRepo -TargetOwnerName MyUserName

Get repository vulnerability alert status

Test-GitHubRepositoryVulnerabilityAlert -OwnerName microsoft -RepositoryName PowerShellForGitHub

Enable repository vulnerability alerts

Enable-GitHubRepositoryVulnerabilityAlert -OwnerName microsoft -RepositoryName PowerShellForGitHub

Disable repository vulnerability alert

Disable-GitHubRepositoryVulnerabilityAlert -OwnerName microsoft -RepositoryName PowerShellForGitHub

Enable repository automatic security fixes

Enable-GitHubRepositorySecurityFix -OwnerName microsoft -RepositoryName PowerShellForGitHub

Disable repository automatic security fixes

Disable-GitHubRepositorySecurityFix -OwnerName microsoft -RepositoryName PowerShellForGitHub

Get repository GitHub Actions permissions

Get-GitHubRepositoryActionsPermission -OwnerName microsoft -RepositoryName PowerShellForGitHub

Set repository GitHub Actions permissions

Set-GitHubRepositoryActionsPermission -OwnerName microsoft -RepositoryName PowerShellForGitHub -AllowedActions All

Get a repository team permission

Get-GitHubRepositoryTeamPermission -OwnerName microsoft -RepositoryName PowerShellForGitHub -TeamName Admins

Set a repository team permission

Set-GitHubRepositoryTeamPermission -OwnerName microsoft -RepositoryName PowerShellForGitHub -TeamName Admins -Permission Admin

Remove a repository team permission

Remove-GitHubRepositoryTeamPermission -OwnerName microsoft -RepositoryName PowerShellForGitHub -TeamName Admins

Branches

Getting a repository branch protection rule

Get-GitHubRepositoryBranchProtectionRule -OwnerName microsoft -RepositoryName PowerShellForGitHub -BranchName master

Creating a repository branch protection rule

New-GitHubRepositoryBranchProtectionRule -OwnerName microsoft -RepositoryName PowerShellForGitHub -BranchName master -RequiredApprovingReviewCount 1

Removing a repository branch protection rule

Remove-GitHubRepositoryBranchProtectionRule -OwnerName microsoft -RepositoryName PowerShellForGitHub -BranchName master

Getting a repository branch pattern protection rule

Get-GitHubRepositoryBranchPatternProtectionRule -OwnerName microsoft -RepositoryName PowerShellForGitHub -BranchPatternName 'Release/**/*'

Creating a repository branch pattern protection rule

New-GitHubRepositoryBranchPatternProtectionRule -OwnerName microsoft -RepositoryName PowerShellForGitHub -BranchPatternName 'Release/**/*' -RequiredApprovingReviewCount 1 -DismissStaleReviews -RequireStrictStatusChecks -StatusCheck 'CICheck'

Removing a repository branch pattern protection rule

Remove-GitHubRepositoryBranchPatternProtectionRule -OwnerName microsoft -RepositoryName PowerShellForGitHub -BranchPatternName 'Release/**/*'

Forks

Get all the forks for a repository

Get-GitHubRepositoryFork -OwnerName microsoft -RepositoryName PowerShellForGitHub

Create a new fork

New-GitHubRepositoryFork -OwnerName microsoft -RepositoryName PowerShellForGitHub

Content

Get html output for a file

Get-GitHubContent -OwnerName microsoft -RepositoryName PowerShellForGitHub -Path README.md -MediaType Html

Get raw output for a file

Get-GitHubContent -OwnerName microsoft -RepositoryName PowerShellForGitHub -Path LICENSE

Get a list of files

Get-GitHubContent -OwnerName microsoft -RepositoryName PowerShellForGitHub -Path Tests

Write a file to a branch of a repository

Set-GitHubContent -OwnerName microsoft -RepositoryName PowerShellForGitHub -Path README.md -CommitMessage 'Adding README.md' -Content '# README' -BranchName master

Traffic

Get the referrer traffic for a repository

Get-GitHubReferrerTraffic -OwnerName microsoft -RepositoryName PowerShellForGitHub

Get the popular content for a repository

Get-GitHubPathTraffic -OwnerName microsoft -RepositoryName PowerShellForGitHub

Get the number of views for a repository

Get-GitHubViewTraffic -OwnerName microsoft -RepositoryName PowerShellForGitHub -Per Week

Get the number of clones for a repository

Get-GitHubCloneTraffic -OwnerName microsoft -RepositoryName PowerShellForGitHub -Per Day

Assignees

Get assignees

Get-GitHubAssignee -OwnerName microsoft -RepositoryName PowerShellForGitHub

Check assignee permission

$HasPermission = Test-GitHubAssignee -OwnerName microsoft -RepositoryName PowerShellForGitHub -Assignee "LoginID123"

Add assignee to an issue

Add-GitHubAssignee -OwnerName microsoft -RepositoryName PowerShellForGitHub -Assignees $assignees -Issue 1

Remove assignee from an issue

Remove-GitHubAssignee -OwnerName microsoft -RepositoryName PowerShellForGitHub -Assignees $assignees -Issue 1

Comments

Get comments from an Issue

Get-GitHubIssueComment -OwnerName microsoft -RepositoryName PowerShellForGitHub -Issue 1

Get Issue comments from a repository

Get-GitHubRepositoryComment -OwnerName microsoft -RepositoryName PowerShellForGitHub -Sort Created -Direction Ascending -Since '2011-04-14T16:00:49Z'

Get a single Issue comment

Get-GitHubIssueComment -OwnerName microsoft -RepositoryName PowerShellForGitHub -CommentID 1

Adding a new comment to an Issue

New-GitHubIssueComment -OwnerName microsoft -RepositoryName PowerShellForGitHub -Issue 1 -Body "Testing this API"

Editing an existing Issue comment

Set-GitHubIssueComment -OwnerName microsoft -RepositoryName PowerShellForGitHub -CommentID 1 -Body "Testing this API"

Removing an Issue comment

Remove-GitHubIssueComment -OwnerName microsoft -RepositoryName PowerShellForGitHub -CommentID 1

Milestones

Get milestones from a repository

Get-GitHubMilestone -OwnerName microsoft -RepositoryName PowerShellForGitHub -Sort DueOn -Direction Ascending -DueOn '2011-04-14T16:00:49Z'

Get a single milestone

Get-GitHubMilestone -OwnerName microsoft -RepositoryName PowerShellForGitHub -Milestone 1

Assign an existing issue to a new milestone

New-GitHubMilestone -OwnerName microsoft -RepositoryName PowerShellForGitHub -Title "Testing this API"
Set-GitHubIssue -OwnerName microsoft -RepositoryName PowerShellForGitHub -Issue 2 -Milestone 1

Editing an existing milestone

Set-GitHubMilestone -OwnerName microsoft -RepositoryName PowerShellForGitHub -Milestone 1 -Title "Testing this API edited"

Removing a milestone

Remove-GitHubMilestone -OwnerName microsoft -RepositoryName PowerShellForGitHub -Milestone 1

Events

Get events from a repository

Get-GitHubEvent -OwnerName microsoft -RepositoryName PowerShellForGitHub

Get events from an issue

Get-GitHubEvent -OwnerName microsoft -RepositoryName PowerShellForGitHub -Issue 1

Get a single event

Get-GitHubEvent -OwnerName microsoft -RepositoryName PowerShellForGitHub -EventID 1

Projects

Get projects for a repository

Get-GitHubProject -OwnerName microsoft -RepositoryName PowerShellForGitHub

Get projects for a user

Get-GitHubProject -UserName octocat

Create a project

New-GitHubProject -OwnerName octocat -RepositoryName PowerShellForGitHub -ProjectName TestProject

Add a column to a project

New-GitHubProjectColumn -Project 1 -ColumnName 'To Do'

Add a card to a column

New-GitHubProjectCard -Column 2 -Note 'Fix this bug'

Add an existing issue as a card to a column

New-GitHubProjectCard -Column 2 -ContentId 3 -ContentType Issue

Move a card to be after a certain card in the same column

Move-GitHubProjectCard -Card 4 -After 5

Move a card to the bottom of another column

Move-GitHubProjectCard -Card 4 -ColumnId 6 -Bottom

Releases

Get releases for a repository

Get-GitHubRelease -OwnerName PowerShell -RepositoryName PowerShell

or with pipelining...

Get-GitHubRepository -OwnerName PowerShell -RepositoryName PowerShell |
    Get-GitHubRelease

Get an individual release for a repository

Get-GitHubRelease -OwnerName PowerShell -RepositoryName PowerShell |
    Select-Object -First 1 |
    Get-GitHubRelease

Create a new release

New-GitHubRelease -OwnerName PowerShell -RepositoryName PowerShell -Tag 11.0

or with pipelining...

Get-GitHubRepository -OwnerName PowerShell -RepositoryName PowerShell |
    New-GitHubRelease -Tag 11.0

Update a release

Set-GitHubRelease -OwnerName PowerShell -RepositoryName PowerShell -Release 123456 -Body 'Updated body'

or with pipelining...

$repo | Set-GitHubRelease -Release 123456 -Body 'Updated body'

# or

$release | Set-GitHubRelease -Body 'Updated body'

Remove a release

Remove-GitHubRelease -OwnerName PowerShell -RepositoryName PowerShell -Release 123456 -Force

or with pipelining...

$repo | Remove-GitHubRelease -Release 123456 -Force

# or

$release | Remove-GitHubRelease -Force

List assets for a release

Get-GitHubReleaseAsset -OwnerName PowerShell -RepositoryName PowerShell -Release 123456

or with pipelining...

$repo | Get-GitHubReleaseAsset -Release 123456

# or

$release | Get-GitHubReleaseAsset

Download a release asset

Get-GitHubReleaseAsset -OwnerName PowerShell -RepositoryName PowerShell -Asset 123456 -Path 'c:\downloads\asset'

or with pipelining...

# Downloads the first asset of the latest release from PowerShell\PowerShell to the file located
# at c:\downloads\asset
Get-GitHubRelease -OwnerName PowerShell -RepositoryName PowerShell -Latest |
    Get-GitHubReleaseAsset |
    Select-Object -First 1 |
    Get-GitHubReleaseAsset -Path 'c:\downloads\asset'

Create a release asset

New-GitHubReleaseAsset -OwnerName PowerShell -RepositoryName PowerShell -Release 123456 -Path 'c:\foo.zip'

or with pipelining...

$release | New-GitHubReleaseAsset -Path 'c:\foo.zip'

# or

@('c:\foo.zip', 'c:\bar.txt') |
    New-GitHubReleaseAsset -OwnerName PowerShell -RepositoryName PowerShell -Release 123456

Update a release asset

Set-GitHubReleaseAsset -OwnerName PowerShell -RepositoryName PowerShell -Asset 123456 -Name 'newFileName.zip'

or with pipelining...

$asset | Set-GitHubReleaseAsset -Name 'newFileName.zip'

Remove a release asset

Remove-GitHubReleaseAsset -OwnerName PowerShell -RepositoryName PowerShell -Asset 123456 -Force

or with pipelining...

$asset | Remove-GitHubReleaseAsset -Force

Gists

Getting gists

# There are many options here:

# 1. Getting all gists for the current authenticated user:
Get-GitHubGist

# 1b. Getting all gists for the current authenticated user that were updated in the past 6 days.
Get-GitHubGist -Since ((Get-Date).AddDays(-6))

# 2. Get all starred gists for the current authenticated user
Get-GitHubGist -Starred

# 3. Get all public gists for a specific user
Get-GitHubGist -UserName 'octocat'

# 4. Get all public gists (well, the first 3000):
Get-GitHubGist -Public

# 5. Get a specific gist
Get-GitHubGist -Gist '6cad326836d38bd3a7ae'

# 5a. List all commits for a specific gist
Get-GitHubGist -Gist '6cad326836d38bd3a7ae' -Commits

# 5b. Get a gist at a specific commit (Sha)
Get-GitHubGist -Gist '6cad326836d38bd3a7ae' -Sha 'de5b9b59d1f28206e8d646c7c8025e9809d0ed73'

# 5c. Get all of the forks for a gist
Get-GitHubGist -Gist '6cad326836d38bd3a7ae' -Forks

Download a gist

Get-GitHubGist -Gist '6cad326836d38bd3a7ae' -Path 'c:\users\octocat\downloads\gist\'

Fork a gist

Fork-GitHubGist -Gist '6cad326836d38bd3a7ae'

Creating a gist

# You can create a gist by specifying a single file's content in-line...
New-GitHubGist -FileName 'foo.txt' -Content 'foo content'

# or by providing one or more files that should be part of the gist
New-GitHubGist -File @('c:\files\foo.txt', 'c:\files\bar.txt')
@('c:\files\foo.txt', 'c:\files\bar.txt') | New-GitHubGist

Removing a gist

Remove-GitHubGist -Gist '6cad326836d38bd3a7ae'

Updating a gist

$gist = New-GitHubGist -FileName 'foo.txt' -Content 'content'

# The main method to use is Set-GitHubGist, however it is quite complicated.
$params = @{
    Description = 'new description' # modifies the description of the gist
    Update = @{
        'foo.txt' = @{
            fileName = 'alpha.txt' # Will rename foo.txt -> alpha.txt
            content = 'updated content' # and will also update its content
        }
        'bar.txt' = @{
            filePath = 'c:\files\bar.txt' # Will upload the content of bar.txt to the gist.
        }
    }
    Delete = @('bar.txt')
    Force = $true # avoid confirmation prompting due to the deletion
}

Set-GitHubGist -Gist $gist.id @params

# Therefore, you can use simpler helper methods to accomplish atomic tasks
Set-GistHubGistFile -Gist $gist.id -FileName 'foo.txt' -Content 'updated content'

# This will update the text in the existing file 'foo.txt' and add the file 'bar.txt'
$gist | Set-GitHubGistFile -File ('c:\files\foo.txt', 'c:\files\bar.txt')

Rename-GistHubGistFile -Gist $gist.id -FileName 'foo.txt' -NewName 'bar.txt'

$gist | Remove-GitHubGistFile -FileName 'bar.txt' -Force

Starring a gist

$gistId = '6cad326836d38bd3a7ae'

# All of these options will star the same gist
Star-GitHubGist -Gist $gistId
Add-GitHubGistStar -Gist $gistId
Set-GitHubGistStar -Gist $gistId -Star
Get-GitHubGist -Gist $gistId | Star-GitHubGist

# All of these options will unstar the same gist
Unstar-GitHubGist -Gist $gistId
Remove-GitHubGistStar -Gist $gistId
Set-GitHubGistStar -Gist $gistId
Set-GitHubGistStar -Gist $gistId -Star:$false
Get-GitHubGist -Gist $gistId | Unstar-GitHubGist

# All of these options will tell you if you have starred a gist
Test-GitHubGistStar -Gist $gistId
Get-GitHubGist -Gist $gistId | Test-GitHubGistStar

Getting gist comments

$gistId = '6cad326836d38bd3a7ae'
$commentId = 1507813

# You can get all comments for a gist with any of these options:
Get-GitHubGistComment -Gist $gistId
Get-GitHubGist -Gist $gistId | Get-GitHubGistComment

# You can retrieve an individual comment like this:
Get-GitHubGistComment -Gist $gistId -Comment $commentId

Adding a gist comment

$gistId = '6cad326836d38bd3a7ae'

New-GitHubGistComment -Gist $gistId -Body 'Hello World'

# or with the pipeline
Get-GitHubGist -Gist $gistId | New-GitHubGistComment -Body 'Hello World'

Changing a gist comment

$gistId = '6cad326836d38bd3a7ae'
$commentId = 1507813

Set-GitHubGistComment -Gist $gistId -Comment $commentId -Body 'Updated comment'

# or with the pipeline
Get-GitHubGist -Gist $gistId -Comment $commentId | Set-GitHubGistComment -Body 'Updated comment'

Removing a gist comment

$gistId = '6cad326836d38bd3a7ae'
$commentId = 1507813

# If you don't specify -Force, it will prompt for confirmation before it will delete the comment

Remove-GitHubGistComment -Gist $gistId -Comment $commentId -Force

# or with the pipeline
Get-GitHubGist -Gist $gistId -Comment $commentId | Remove-GitHubGistComment -Force

Deployment Environments

Adding a new environment

New-GitHubDeploymentEnvironment -OwnerName microsoft -RepositoryName TestRepo -Environment Test

Getting details of an environment

Get-GitHubDeploymentEnvironment -OwnerName microsoft -RepositoryName TestRepo -Environment Test

Updating an environment

Set-GitHubDeploymentEnvironment -OwnerName microsoft -RepositoryName TestRepo -Environment Test -DeploymentBranchPolicy ProtectedBranches

Removing an environment

Remove-GitHubDeploymentEnvironment -OwnerName microsoft -RepositoryName TestRepo -Environment Test

Advanced

Migrating blog comments to GitHub issues

@LazyWinAdmin used this module to migrate his blog comments from Disqus to GitHub Issues. See blog post for full details.

# Get your repo
$repo = Get-GitHubRepository -OwnerName <yourName> -RepositoryName RepoName

# Create an issue
$issue = $repo | New-GitHubIssue -Title $IssueTitle -Body $body -Label 'blog comments'

# Create Comment
$issue | New-GitHubIssueComment -Body $CommentBody

# Close issue
$issue | Set-GitHubIssue -State Closed

Codespaces

Getting codespaces

# Get all codespaces for the current authenticated user
Get-GitHubCodespace

# Get all codespaces for the current authenticated user in a repository
Get-GitHubCodespace -OwnerName microsoft -RepositoryName TestRepo

# Get a codespace by name
Get-GitHubCodespace -CodespaceName 'microsoft-symmetrical-chainsaw-7q4vp6v7q3pwqq'

Create a codespace

# Create a codespace in the specified repository by id
New-GitHubCodespace -RepositoryId 582779513

# Create a codespace in the specified repository by name
New-GitHubCodespace -OwnerName microsoft -RepositoryName TestRepo

# Create a codespace in the specified repository by id from a pull request
New-GitHubCodespace -RepositoryId 582779513 -PullRequest 508

# Create a codespace in the specified repository by name from a pull request
New-GitHubCodespace -OwnerName microsoft -RepositoryName TestRepo -PullRequest 42

# Create a codespace in repository from pipeline
$repo = Get-GitHubRepository -OwnerName microsoft -RepositoryName TestRepo
$repo | New-GitHubCodespace

# Create a codespace in repository from pipeline with options
$newGitHubCodespaceParms = @{
    DisplayName = 'PowerShellForGitHub usage'
    Geo = 'UsWest'
    Machine = 'basicLinux32gb'
    NoMultipleRepoPermissions = $true
    IdleRetentionPeriodMinutes = 10
    TimeoutMinutes = 5
}
$codespace = $repo | New-GitHubCodespace @newGitHubCodespaceParms

Removing a codespace

$codespaceName = 'microsoft-symmetrical-chainsaw-7q4vp6v7q3pwqq'

# Remove a codespace for the current authenticated user
Remove-GitHubCodespace -CodespaceName $codespaceName

Starting a codespace

$codespaceName = 'microsoft-symmetrical-chainsaw-7q4vp6v7q3pwqq'

# Starting a codespace (asynchronous)
Start-GithubCodespace -CodespaceName $codespaceName

# Starting a codespace (wait for Available)
Start-GithubCodespace -CodespaceName $codespaceName -Wait

Stopping a codespace

$codespaceName = 'microsoft-symmetrical-chainsaw-7q4vp6v7q3pwqq'

# Stopping a codespace (asynchronous)
Stop-GithubCodespace -CodespaceName $codespaceName

# Stopping a codespace (wait for Shutdown)
Stop-GithubCodespace -CodespaceName $codespaceName -Wait

Codespaces organizations

Getting organization Codespaces

# Get all codespaces for an Organization
Get-GitHubCodespace -OrganizationName microsoft

# Get all codespaces for a specific organization user
Get-GitHubCodespace -OrganizationName microsoft -UserName octocat

Removing an organization Codespace

$codespaceName = 'microsoft-symmetrical-chainsaw-7q4vp6v7q3pwqq'

# Remove a codespace for an organization user
Remove-GitHubCodespace -OrganizationName microsoft -UserName octocat -CodespaceName $codespaceName

Stopping an organization Codespace

$codespaceName = 'microsoft-symmetrical-chainsaw-7q4vp6v7q3pwqq'

# Stopping a codespace (wait for Shutdown)
Stop-GithubCodespace -OrganizationName microsoft -UserName octocat -CodespaceName $codespaceName -Wait