Repository files navigation

• Overview
• What's New
• Current API Support
• Installation
• Configuration
• Usage
• Developing and Contributing
• Legal and Licensing
• Governance
• Code of Conduct
• Reporting Security Issues
• Privacy Policy

This is aPowerShellmodulethat provides stateless command-line interaction and automation for theGitHub v3 API.

Embracing the benefits of PowerShell, it hasfull support for pipelining, allowing you pipe the output ofvirtually any command into any other command within the module.

Check outCHANGELOG.md to review the details of the current release as well asall past releases.

At present, this module can:

• Query, create, update and removeRepositories including
  • Query, create and removeBranches, as wellas the associated branch protection rules.
  • Query and create newForks
  • Query and createContent in a repo.
  • Query the languages and tags in a repository, and and query/update its topics.
  • Change repository ownership.
  • Query, enable and disable security and vulnerability alerts.
  • Query and set GitHub Actions permission.
  • Query, set and remove team permissions.
  • Query varioustraffic reports includingreferral sources and paths, page views and clones.
• Query, create, edit, lock/unlockIssues andall of their related properties:
  • Query, check, add and removeAssignees
  • Query, create, edit and removeIssue Comments
  • Query, create, edit and removeLabels
  • QueryEvents and thetimeline
  • Query, create, edit and removeMilestones
• Query and createPull Requests
• Querycollaborators
• Querycontributors
• Queryorganizations and their members.
• Query and updateUsers
• Query, create, edit and removeTeams,and Query their members.
• Query, create, edit and removeProjects, along withProject Columns andProject Cards
• Query, create, edit and removeReleases andassociated content/assets.
• Query, create, edit, remove, fork, and (un)stargists,as well as gist comments.
• Query, edit and removereactions on Issues andPull Requests.
• Query, create, edit and removeDeployment Environments
• Miscellaneous functionality:
  • Get allCodes of Conduct as well as thatof a specific repo.
  • Get allGitHub emojis
  • Getgitignore templates
  • Getcommonly used licenses as well as that fora specific repository.
  • Convert markdown to the equivalent HTML
  • Get your currentrate limit for API usage.

Development is ongoing, with the goal to add broad support for the entire API set.

For a comprehensive look at what work is remaining to be API Complete, refer toIssue #70.

Reviewexamples to see how the module can be used to accomplish some of these tasks.

You can get latest release of the PowerShellForGitHub on thePowerShell Gallery

Install-Module-Name PowerShellForGitHub

To avoid severe API rate limiting by GitHub, you should configure the module with your own personalaccess token.

1. Create a new API token by going tohttps://github.com/settings/tokens/new (provide a descriptionand check any appropriate scopes)
2. CallSet-GitHubAuthentication, enter anything as the username (the username is ignored butrequired by the dialog that pops up), and paste in the API token as the password. That will besecurely cached to disk and will persist across all future PowerShell sessions.If you ever wish to clear it in the future, just callClear-GitHubAuthentication).

For automated scenarios (like GithHub Actions) where you are dynamically getting the access tokenneeded for authentication, refer toExample 2 inGet-Help Set-GitHubAuthentication -Examplesfor how to configure in a promptless fashion.

Alternatively, youcould configure PowerShell itself to always pass in a plain-text access tokento any command (by setting$PSDefaultParameterValues["*-GitHub*:AccessToken"] = "<access token>"),although keep in mind that this is insecure (any other process could access this plain-text value).

A number of additional configuration options exist with this module, and they can be configuredfor just the current session or to persist across all future sessions withSet-GitHubConfiguration.For a full explanation of all possible configurations, run the following:

Get-HelpSet-GitHubConfiguration-ShowWindow

For example, if you tend to work on the same repository, you can save yourself a lot of typingby configuring the default OwnerName and/or RepositoryName that you work with. You can alwaysoverride these values by explicitly providing a value for the parameter in an individual command,but for the common scenario, you'd have less typing to do.

Set-GitHubConfiguration-DefaultOwnerName PowerShellSet-GitHubConfiguration-DefaultRepositoryName PowerShellForGitHub

Be warned that there are some commands where you may want to only ever supply the OwnerName(like if you're callingGet-GitHubRepository and want to see all the repositories ownedby a particular user, as opposed to getting a single, specific repository). In cases like that,you'll need to explicitly pass in$null as the relevant parameter value as a temporary overridefor your default if you've set a default for one (or both) of these values.

There are more great configuration options available. Just review the help for that command forthe most up-to-date list!

To set the configuration to use a GitHub Enterprise server instead of GitHub.com, simply supplytheApiHostName parameter with the hostname of your GitHub Enterprise server.

Set-GitHubConfiguration-ApiHostName"github.contoso.com"

Example command:

$issues=Get-GitHubIssue-Uri'https://github.com/microsoft/PowerShellForGitHub'

For more example commands, please refer toUSAGE.

Please see theContribution Guide for information on how to develop andcontribute.

If you have any problems, please consultGitHub Issuesto see if has already been discussed.

If you do not see your problem captured, please filefeedback.

PowerShellForGitHub is licensed under theMIT license.

Governance policy for this project is describedhere.

For more info, seeCODE_OF_CONDUCT

Please refer toSECURITY.md.

For more information, refer to Microsoft'sPrivacy Policy.