`Get-GitHubEvent` is currently broken if the issue contains and event that includes the "label" or "labels" property. This is because `Add-GitHubEventAdditionalProperties` treats the labels in the event object as full fledged label objects that normally contain a URL property and other additional pieces of data. The label property in a `GitHub.Event` is a lighter-weight object that simply contains the string for the label and color that was changed, it is not the full object that you would typically receive from a call like `Get-GithubLabel`.
Updated to add a new `GitHub.LabelSummary` type to describe this scenario, as well as passing in the needed `RepositoryUrl` when adding the additional label properties.
GitHub will return back a `202` response when the result for the query is not yet ready. GitHub requests that we "give the job a few moments to complete, and then submit the request again."
We already had the configuration value `RetryDelaySeconds` which covered how many seconds we would sleep before trying the request again. We tried the request again via a recursive call to `Invoke-GHRestMethod`.
It turns out that there's something going on with GitHub right now, and trying to get contributor statistics for a completely new repository never returns back a 200, even after 145 retry attempts over 72 minutes.
That many recursive calls ends up causing a call depth overflow exception with PowerShell. While this scenario should be an edge-case, nonetheless it seems better to remove the possibility of this error from occurring by modifying the retry logic to be a loop rather than a recursive call.
I've also added a new configuration value: `MaximumRetriesWhenResultNotReady` to help control and limit the number of retries that we'll attempt in this situation, ultimately throwing an exception if the retry limit is exceeded without a 200 response.
Finally, I've disabled the `When getting Github Repository Contributors with Statistics` test until the problem is fixed on the GitHub end. I've disabled the test by commenting the test out vs using the disable keyword to avoid the Pester failure for disabled tests, and I've opened a [support issue](https://github.community/t/unable-to-retrieve-contributor-statistics-for-a-brand-new-repo/136658) on this problem.
The Build-* verb is new to PowerShell Core and so was considered
unapproved for Windows PowerShell. Given that these are internal
helper methods and it _is_ an approved verb in PS Core, keeping as-is
and just marking these warning instances to be suppressed.
This adds a new script utility, `Build-Wiki.ps1`, which can be used to auto-generate the documentation for the Wiki. This uses the [PlatyPS](https://github.com/PowerShell/PlatyPS) module to generate the actual help documentation.
Relevant notes:
* This will generate the `Home.md`, `_sidebar.md`, and `_footer.md` files for the Wiki if they don't already exist in the destination directory.
* If they do already exist, it intelligently updates the content, only replacing the parts that it generated itself (denoted with
comments in the markdown content itself).
* At present, this is not being hooked-up to CI because I don't want to deal with storing credentials that have admin access
to the actual repo.
Tip of the hat to @X-Guardian for the suggestion and the initial help with writing this out.
Resolves#208
In Azure Function Apps, the special `MyDocuments` folder resolves to an empty string, which means that the default `logPath` gets stored as an empty string.
3094c9789c/GitHubConfiguration.ps1 (L650-L657)3094c9789c/GitHubConfiguration.ps1 (L671)
This causes problems when `Write-Log` is called by any other function, because we directly assign the current configuration value for `LogPath` as the parameter's default, which throws an exception when an empty string is assigned.
3094c9789c/Helpers.ps1 (L142)
In this scenario, we'll fall back to using the `LocalApplicationDataFolder` folder and writing a verbose message to the user letting them know this has happened. I've opted for a verbose message as opposed to a warning to avoid a constant annoying warning for users. The alternate path is documented in the updated USAGE.md, and it's also retrievable by calling `Get-GitHubConfiguration -Name LogPath`.
Documentation has also been updated to reflect this behavior change.
Fixes#282
Updated the summary of the current API support in the README to account
for the recent `0.15.0` changes. Also added a direct link to the
CHANGELOG as well.
Added a number of additional details for the breaking changes being
introduced in order to make it easier for existing users to migrate
their code.
Some very minor changes have been additionally made to fix some
documentation or parameter typename issues. Given that 0.15.0 still
hasn't been officially published yet, these changes will be part of
the eventual 0.15.0 release.
#257 did a fantastic job closing the gap on missing functionality in the module related to GitHub Teams.
This PR just adds onto that work by providing options that will reduce the need for additional queries during common operations.
* `Get-GitHubTeam`: **Breaking Change** Looking up a team by its `ID` has been deprecated per GitHub documentation. Removed that functionality and added the ability to look up by `slug` instead. This also means that you can now pipe in a team and get back the specific result without needing to filter through all org results.
* `Get-GitHubTeamMember`: Updated to use the `slug` instead of the team `ID`.
* `New-GitHubTeam`: Added ability to pass in the `ParentTeamId` (also via the pipeline) to avoid the need to query through all org teams.
* `Set-GitHubTeam`: Added ability to pass in the team `slug` (also via the pipeline) to avoid the need to query through all org teams. Similar to `New-GitHubTeam`, also added the ability to pass-in the `ParentTeamId` to avoid the full org team lookup.
* `Remove-GitHubTeam`: Added ability to pass in the team `slug` (also via the pipeline) to avoid the need to query through all org teams.
* Added `Rename-GitHubTeam` as a helper/wrapper on top of `Set-GitHubTeam`
* Added additional pipeline tests for existing functions
* Added new tests for `Rename-GitHubTeam` and `Get-GitHubTeamMember`
* Small update to formatters to simplify the display of the team parent
References: [GitHub Teams API](https://developer.github.com/v3/teams/)
All state-changing commands (with the exception of `New-*`) are now silent by default. Users can pass-in `-PassThru` to make them return the result that used to be returned by default.
Users can revert back to the previous behavior by leveraging the new configuration value: `DefaultPassThru`.
Resolves#217
* Updates `New-GitHubBranch` to be able to take a `GitHub.Branch` object as pipeline input (for the base branch)
* Updates `New-GitHubBranch` to be able to take in a `Sha` so that a branch can be created from an arbitrary commit (which also enables a new branch to be created from a `GitHub.Branch` pipeline input value without needing to perform an additional query on `BranchName` to get its `Sha`)
* Updates `GitHub.Branch` to have `Sha` as a top-level property.
* Updated existing tests and added additional tests.
Reference: [GitHub Refs API](https://developer.github.com/v3/git/refs/)
Fixes#261
The `NoStatus` parameter (and `DefaultNoStatus` config value) were deprecated as part of #253 when we stopped showing status except for multi-page requests that exceeded some minimum number of pages.
At that time, `NoStatus` (and `DefaultNoStatus`) were not removed in order to minimize the churn to the module. However, keeping it in is adding unnecessary complexity to the module as we continue to expand what the module can do.
This change removes `NoStatus` (and `DefaultNoStatus`) from the module entirely. The only impact that this may cause is with users who are currently using one (or both) of them. This breaking change impact should be minimal, but its best for the breaking change to be part of the coming release which already has a number of other breaking changes as well, as opposed to having more breaking changes in a successive release.
Adds the following functions:
- `Add-GitHubTeam`
- `Update-GitHubTeam`
- `Remove-GitHubTeam`
It also adds the `TeamName` parameter to the `Get-GitHubTeam` function to allow getting team details by team name, which is used by the new functions.
Pester tests have also been added for the following functions:
- `Get-GitHubTeam`
- `Add-GitHubTeam`
- `Update-GitHubTeam`
- `Remove-GitHubTeam`
Positional Binding has been set as `false` for the three functions, and `Position` attributes added to the function's mandatory parameters.
Type view formats have been added for the `GitHub.TeamSummary` and `GitHub.Team` types.
API Reference: [GitHub Teams API](https://developer.github.com/v3/teams/)
Fixes the pipeline input for the following GitHub Repository functions:
- `Disable-GitHubRepositoryVulnerabilityAlert`
- `Enable-GitHubRepositorySecurityFix`
- `Disable-GitHubRepositorySecurityFix`
The unit tests for the functions are also updated to add pipeline tests.
Fixes#270
This PR fixes the `Describe 'GitHubRepositories\Enable-GitHubRepositorySecurityFix'` and `Describe 'GitHubRepositories\Disable-GitHubRepositorySecurityFix'` GitHubRepositories tests following on from the change to the GitHub Automated Security Fixes API.
Reference: [Enable Automated Security Fixes](https://docs.github.com/en/rest/reference/repos#enable-automated-security-fixes)
Fixes#269
Improves and standardizes the WhatIf/Confirm ('ShouldProcess') processing across all the functions.
* Moved the `$PSCmdlet.ShouldProcess` check out of `Invoke-GHRestMethod` and added it to the calling functions with the correct operation and target.
* Added `WhatIf:$false` and `Confirm:$false` to the `Out-File` Cmdlet call in the `Write-Log` function in the Helpers module. This will prevent the `Write-Log` function displaying `WhatIf` and `Confirm` prompts.
* Removed `ShouldProcess` from non-state changing functions.
* Modified the current `ShouldProcess` conditions to use an early return.
* Modified the `Set-GitHubIssueLabel` function to remove `ConfirmImpact='High'` and set `ConfirmPreference` to 'Low' if no labels have been specified instead.
* Modified the `Update-GitHubRepository` function to remove `ConfirmImpact='High'` and set `ConfirmPreference` to 'Low' if the repo is being renamed instead.
This completes the required work to support the full set of API's around gists.
It adds the following functions:
* `Get-GitHubGist`
* `Remove-GitHubGist`
* `Copy-GitHubGist` (aka. `Fork-GitHubGist`)
* `Add-GitHubGistStar`
* `Remove-GitHubGistStar`
* `Set-GitHubGistStar` (just a wrapper around `Add/Remove-GitHubGistStar`
* `Test-GitHubGistStar`
* `New-GitHubGist`
* `Set-GitHubGist`
* `Rename-GitHubGistFile` (exposed helper function)
* `Remove-GitHubGistFile` (exposed helper function)
* `Set-GitHubGistFile` (exposed helper function, also known as `Add-GitHubGistFile`)
* `Get-GitHubGistComment`
* `Set-GitHubGistComment`
* `New-GitHubGistComment`
* `Remove-GitHubGistComment`
This also adds formatters for all newly introduced types: `GitHub.Gist`, `GitHub.GistCommit`, `GitHub.GistDetail`, and `GitHub.GistFork`.
Positional Binding has been set as `false`, and `Position` attributes added to the functions' mandatory parameters.
References:
[GitHub Gist](https://developer.github.com/v3/gists/)
[GitHub Gist Comments](https://developer.github.com/v3/gists/comments/)
Fixes#32
This completes the required work to support the set of Releases API's.
It adds the following functions:
* `New-GitHubRelease`
* `Set-GitHubRelease`
* `Remove-GitHubRelease`
* `Get-GitHubReleaseAsset`
* `New-GitHubReleaseAsset`
* `Set-GitHubReleaseAsset`
* `Remove-GitHubReleaseAsset`
`Invoke-GHRestMethod` has been updated to be able to upload a file (via the new `InFile` parameter) and download a file (via the `Save` switch which will cause it to return back a `FileInfo` object of a temporary file which can then be renamed as seen fit by the caller).
This also adds formatters for `GitHub.Release` and `GitHub.ReleaseAsset`.
Positional Binding has been set as `false` for the three functions, and `Position` attributes added to the function's mandatory parameters.
Reference: [GitHub Releases](https://developer.github.com/v3/repos/releases/)
Fixes#47Fixes#110
This is re-implementing #265 in a more robust way, thanks to a suggestion from @X-Guardian in #267.
Instead of adding in one-off sleeps throughout the test codebase, there is now a new configuration value `StateChangeDelaySeconds`) that will allow us to insert a delay before returning the result of _any_ state change request.
This should ideally consistently add reliability throughout the entire test codebase.
We're seeing some inconsistent failures in some of the Pester tests.
The hypothesis is that GitHub may need a little bit more time after the creation of objects before performing certain operations on them (like renaming repos), or may need more time after deleting them before it will successfully return a 404 on a successive Get request.
I have added a number of `Start-Sleep`'s throughout the test codebase wherever we've encountered inconsistent failures, and that appears to have resolved the problem. We may need to continue to do more of these if additional ones pop up.
The duration of the sleep itself is controlled by `$script:defaultSleepSecondsForReliability` which is defined in `Tests/Common.ps1`.
Long term, I have opened #267 which poses the idea of switching over to mocking out `Invoke-WebRequest` for the majority of the tests, and instead focus on validating the data that it's sending matches the expected values per the API documentation, and having just a limited number of tests that do actual end-to-end testing.
Fixes#264
Adds the following functions to the `GitHubBranches` module:
* `New-GitHubRepositoryBranch`
* `Remove-GitHubRepositoryBranch`
#### References
[GitHub Refs API](https://developer.github.com/v3/git/refs/)
`ConvertFrom-Json` defaults numbers to different types depending on the PowerShell version.
PS5 defaults numbers to `[Int32]` while PS7 defaults numbers to `[Int64]`, but both versions default to `[Int32]` in a `[PSCustomObject]`.
Due to this, if you had a number config value saved, on PS7 it would be ignored and the default value would be used because the expected and actual types wouldn't match.
I've updated `Resolve-PropertyValue` to have equivalence logic for number types to avoid this issue.
This updates the CI build with two new features:
1. **Validation against Windows PS7 (PowerShell Core)**
This pipeline previously had three platforms that it tested against:
* `Windows PS5`
* `Linux PS7 (PowerShell Core)`
* `macOS PS7 (PowerShell Core)`
With this change, we add a fourth platform: `Windows PS7 (PowerShell Core)`
2. **Build queuing**
The unit tests operate against live GitHub accounts (as opposed to mocking out the execution of the API calls). Each platform has its own account that it operates against to alllow each platform to be tested in parallel. However, if more than one build is queued at once, then the builds can start to stomp over the expected state in the tests accounts. This change adds a new `job` to the pipeline which will create a "queue" of running builds by only allowing a build to continue processing once all previously queued builds have completed.
Initial idea came from here:
https://developercommunity.visualstudio.com/idea/365730/prevent-parallel-execution-of-the-same-build-defin.html
- Fixes#239
* Reimagining status for the module
Status for commands was originally added to this module based on my experience with other REST API's where individual commands could easily take 10-20 seconds.
Practical usage has shown that most GitHub requests in reality take under one second. The additional work that PowerShell has to do in order to display progress to the user can easily make the overall command take 4-6 times longer than its actual execution time.
Therefore, status is being ripped out of this module (for the most part). `Invoke-GHRestMethod` and `Invoke-SendTelemetryEvent` no longer have bifurcating execution paths based on the value of `$NoStatus`. Everything runs synchronously now on the command prompt.
* `DefaultNoStatus` has been deprecated. Its value will be ignored.
* The `NoStatus` switch has not been removed from the module commands in order to avoid a breaking change. It may be removed in a future update.
* `Invoke-GHRestMethod -ExtendedResult` has been updated to include the next page's number and the total number of pages for the REST request.
* A new configuration value has been added: `MultiRequestProgressThreshold
`Invoke-GHRestMethodMultipleResult` will display a ProgressBar to the user tracking the number of remaining requests for the overall execution of the requested command based on this threshold value. It will only display the progress bar if the number of requets needed meets or exceeds this threshold value. This defaults to 10, and can be disabled with a value of 0.
Practical usage has shown that this adds less than a second of additional time to the overall execution of a multi-request command (quite different than the previous status).
* `Wait-JobWithAnimation` has been removed since it's no longer used.
Fixes#247
Added in #221, `New-GitHubRepositoryFromTemplate was not capturing the passed-in value for the RepositoryName if provided via a Uri parameter.
There was a pipeline test in place, however it missed this fact because it was only testing the pipeline input scenario using `-WhatIf`, and the error was only found when calling the actual REST API and GitHub noticed that the `RepositoryName` was missing from the URI.
Pull #251 changed the repo targeted by the forks tests from `microsoft/PowerShellForGitHub` to `octocat/Hello-World` in order to prevent the accidental deletion of real forks when running the UT's locally against your own account.
In practice, this almost doubled the execution time of the UT's, because the execution time of the Forks API's took so much longer against a repo with 1400+ forks.
Changing the test over to use a repo that currently only has 39 forks (several orders of magnitude fewer).
This attempts to rectify some improper verb usage in the module based on the explanations of intended verb usage from [previous PowerShell documentation](https://web.archive.org/web/20171222220053/https://msdn.microsoft.com/en-us/library/windows/desktop/ms714428(v=vs.85).aspx).
* We're standardizing on the following pattern for most object actions:
`Get` / `Set` / `New` / `Remove`
* We will continue to alias `Remove-*` as `Delete-*`.
* When possible, this change attempts to avoid breaking changes by re-aliasing the newly named functions with their previous names. This was not possible in one instance, hence this is still a breaking change (although based on telemetry, it should be minimally impacting).
Result:
* `Update-GitHubCurrentUser` -> `Set-GitHubProfile` `[Alias('Update-GitHubCurrentUser')]`
* `Update-GitHubIssue` -> `Set-GitHubIssue` `[Alias('Update-GitHubIssue')]`
* `Update-GitHubRepository` -> `Set-GitHubRepository` `[Alias('Update-GitHubRepository')]`
* `New-GitHubAssignee` -> `Add-GitHubAssignee` `[Alias('New-GitHubAssignee')]`
* [breaking] `Update-GitHubLabel` -> `Set-GitHubLabel` `[Alias('Update-GitHubLabel')]`
* [breaking] `Set-GitHubLabel` -> `Initialize-GitHubLabel` `<no alias due to above>`
Changing an existing label has much more regular usage than replacing all of the labels in a repository, hence allowing the _new_ `Set-GitHubLabel` to keep the alias of `Update-GitHubLabel`.
Our usage of the `Set-*` verb in general is a bit arguable based on the documentation ... in theory `Edit-*` might be a better fit since we're _editing_ aspects of an object as opposed to _replacing_ the entire content of an object. However, I think `Set-*` _feels_ ok in this module. We're _setting_ the state of these objects. Again...arguable, but this is a much smaller breaking change to get to a consistent terminology state.
* Fixes a regression [introduced by #242 unfortunately](17f6122d78 (diff-34a614678760cc83c5a91ad95ae240e5R86)) when I was reducing the lines in the module that exceeded 100 chars.
Specifically (note the `=Message` instead of the `-Message`):
17f6122d78/UpdateCheck.ps1 (L86)
* Updates the web request to suppress the progress bar using `$ProgressPreference = 'SilentlyContinue'`
* Adds a `-Force` switch to force the update check to happen again to make future debugging scenarios easier.
Fixes#249Fixes#250
Updates the Pester tests for the `GitHubRepositories` module to increase the code coverage.
This also:
* Refactors `Get-GithubRepository` to remove a code path that could never be taken
* Adds a `ValidateSet` to the `Affiliation` parameter of the `Get-GitHubRepository` function
* Fixes the Comment Based Help descriptions for the `Get-GitHubRepositoryCollaborator` and `Move-GitHubRepositoryOwnership`
* Adds formatting for all of the types exposed in GitHubRepositories.ps1.
* Fixes the `OutputType` for RepositoryCollaborator and RepositoryContributor.
Simon Heather
Pepe Rivera
Jonathan Moss
Howard Wolosky
Ted Hudek
John
Jack Samuel S
Tyler James Leonhardt
Christoph Bergmeister [MVP]