![[GitHub version]](https://badge.fury.io/gh/microsoft%2FPowerShellForGitHub.svg){kind=icon}
- 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 a PowerShell module that provides stateless command-line interaction and automation for the GitHub v3 API.
Embracing the benefits of PowerShell, it has full support for pipelining, allowing you pipe the output of virtually any command into any other command within the module.
Check out CHANGELOG.md to review the details of the current release as well as all past releases.
At present, this module can:
- Query, create, update and remove Repositories including
- Query, create and remove Branches, as well as the associated branch protection rules.
- Query and create new Forks
- Query and create Content 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 various traffic reports including referral sources and paths, page views and clones.
- Query, create, edit, lock/unlock Issues and
all of their related properties:
- Query, check, add and remove Assignees
- Query, create, edit and remove Issue Comments
- Query, create, edit and remove Labels
- Query Events and the timeline
- Query, create, edit and remove Milestones
- Query and create Pull Requests
- Query collaborators
- Query contributors
- Query organizations and their members.
- Query and update Users
- Query, create, edit and remove Teams, and Query their members.
- Query, create, edit and remove Projects, along with Project Columns and Project Cards
- Query, create, edit and remove Releases and associated content/assets.
- Query, create, edit, remove, fork, and (un)star gists, as well as gist comments.
- Query, edit and remove reactions on Issues and Pull Requests.
- Miscellaneous functionality:
- Get all Codes of Conduct as well as that of a specific repo.
- Get all GitHub emojis
- Get gitignore templates
- Get commonly used licenses as well as that for a specific repository.
- Convert markdown to the equivalent HTML
- Get your current rate 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 to Issue #70.
Review examples to see how the module can be used to accomplish some of these tasks.
You can get latest release of the PowerShellForGitHub on the PowerShell Gallery
Install-Module -Name PowerShellForGitHubTo avoid severe API rate limiting by GitHub, you should configure the module with your own personal access token.
- Create a new API token by going to https://github.com/settings/tokens/new (provide a description and check any appropriate scopes)
- Call
Set-GitHubAuthentication, enter anything as the username (the username is ignored but required by the dialog that pops up), and paste in the API token as the password. That will be securely 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 token needed for authentication, refer to
Example 2inGet-Help Set-GitHubAuthentication -Examplesfor how to configure in a promptless fashion.Alternatively, you could configure PowerShell itself to always pass in a plain-text access token to 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 configured
for just the current session or to persist across all future sessions with Set-GitHubConfiguration.
For a full explanation of all possible configurations, run the following:
Get-Help Set-GitHubConfiguration -ShowWindowFor example, if you tend to work on the same repository, you can save yourself a lot of typing by configuring the default OwnerName and/or RepositoryName that you work with. You can always override 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 PowerShell
Set-GitHubConfiguration -DefaultRepositoryName PowerShellForGitHubBe warned that there are some commands where you may want to only ever supply the OwnerName (like if you're calling
Get-GitHubRepositoryand want to see all the repositories owned by a particular user, as opposed to getting a single, specific repository). In cases like that, you'll need to explicitly pass in$nullas the relevant parameter value as a temporary override for 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 for the most up-to-date list!
To set the configuration to use a GitHub Enterprise server instead of GitHub.com, simply supply
the ApiHostName 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 to USAGE.
Please see the Contribution Guide for information on how to develop and contribute.
If you have any problems, please consult GitHub Issues to see if has already been discussed.
If you do not see your problem captured, please file feedback.
PowerShellForGitHub is licensed under the MIT license.
Governance policy for this project is described here.
For more info, see CODE_OF_CONDUCT
Please refer to SECURITY.md.
For more information, refer to Microsoft's Privacy Policy.