Usage
PSAdvantage was coded with flexibility and easiness in mind. Using it requires a couple of setup steps. Once a basic setup has been done, you can start using it.
| Name | Help |
|---|---|
| Get-GHAllReports | Gets all metrics from a GitHub repo, Releases, Issues, and Pull Requests. Exports to Excel |
| Get-GHBaseRestURI | |
| Get-GHIssue | Get issues in a GitHub repository |
| Get-GHIssueReport | Get issues in a GitHub repository, and save them to Excel, and make a pivot table |
| Get-GHJob | Lists workflow jobs. A workflow job is a set of steps that execute on the same runner |
| Get-GHLatestJob | Gets the last job that ran for the specified repository |
| Get-GHLatestRun | Gets the last job that ran for the specified repository |
| Get-GHLog | Download a plain text file of logs for a workflow job |
| Get-GHMetrics | Gets GitHub metrics on repositories |
| Get-GHPullRequest | Get pull requests in a GitHub repository |
| Get-GHPullRequestReport | Get pull requests in a GitHub repository, and save them to Excel, and make a pivot table |
| Get-GHRelease | Get releases in a GitHub repository |
| Get-GHReleaseReport | Get releases in a GitHub repository, and export them to Excel |
| Get-GHRepo | Get info on a repo |
| Get-GHRun | Lists all workflow runs for a repository |
| Get-GHSecret | Gets the secrets name for the specified repo |
| Get-GHStargazers | Gets GitHub stargazers on repositories |
| Get-GHWorkflow | Lists the workflows in a repository |
| Import-PSAdvantageConfig | Reads PSAdvantage configuration, has the GitHub Access token |
| Invoke-Advantage | Invoke the GitHub Actions Automation Framework |
| Invoke-GHPush | Commits and pushes a local changes to GitHub |
| Invoke-GHWorkflow | Trigger a GitHub Actions workflow run |
| New-GHRepo | Creates a new private GitHub repository |
| Remove-GHRepo | Removes a repository |
| Remove-GHRepoWorkflowFile | Deletes a file in a repository |
| Remove-GHSecret | Deletes a secret in a repository using the secret name |
| Set-GHRepoVisibility | Set the visibility of a repository |
| Stop-GHRun | Stops a workflow run using its id |
| Test-GHPath | Determines whether all elements of a GitHub path exists |
| Test-GHRepo | Determines if a GitHub repository exists |
| Test-GHSecret | Test of the names secret exists in the specified repo |
Function: New-GHRepo
Creates a new repository in the account of the AccessToken holder. By default, it creates a private repository, if you intend to create a public one, use the -IsPublic switch.
Usage: New-GHRepo -reponame {repo_name} [options]
Parameter: -AccessToken
Specify the access token if you do not want to hardcode your TOKEN within the config.ps1 file. However, this parameter will always be required and have to be supplied with every instruction.
For Example
Usage: New-GHRepo -reponame {repo_name} -AccessToken 13a23b423a423a4b234a2b3a4b23a42b34bb5b4356b5c
Function: Invoke-Advantage
Parameter: -template
Lets you use the templating engine for creating new workflows. It accepts a template name and instructs the tool to add your command to it (if the template is configured to use one) and then creates the workflow on basis of that template. For more info, see how to write a template.
NOTE: The template MUST be present in the
templates/folder where the module is installed. The string passed to the argument should be the name of the file without the.ymlextension. e.g. If your template istemplates/mytemplate.yml, then you should use-template mytemplate.
Example: Invoke-Advantage -owner dfinke -reponame pstest -template basic-powershell
DOUBLE NOTE: The template parameter is dynamic. You can use autocompletion to see a list of templates in the
templates/folder
Parameter: -command
Template commands are yet another powerful feature. If you have a single template which you want to execute with different inputs, this is the switch for you.
NOTE: For
-commandto work, the template must have the command directive mentioned explicitly.
Example: Invoke-Advantage dfinke xyz -template basic-powershell -command '$PSVersionTable'
The above example will create a new workflow using the basic-powershell.yml and will print out $PSVersionTable.
Function: New-GHRepo
Parameter: -clone
Clones a repository into the custom/ folder. You would usually use this switch if you want to upload some new scripts in your repository and create a workflow based upon them.
Example: New-GHRepo testing -clone
Function: Invoke-GHPush
Commits and pushes locally cloned repositories to GitHub. Its the tool's way of doing git add . && git commit. Particularly useful for setting up things in a repository after a fresh clone. Accepts a repository name present within the custom/ directory.
Example:
$reponame = 'testing'
New-GHRepo $reponame -clone
Copy-Item ..\*.ps1 .\custom\$reponame
Invoke-GHPush $reponameWe are simply creating and cloning a new repository. By default the --clone switch will clone the repository within the custom/ folder. Next we copy some scripts from a different directory to the freshly cloned repository and then commit and push the new files.
Function: Invoke-Advantage
Parameter: -savelogs
Gives you the option to save logs for a specific run. Should be used whenever you're triggering workflows. Accepts a directory path name.
Example: Invoke-Advantage dfinke $reponame -template basic-powershell -command '"Hello World!"' -saveLogs ./logsDir
Deletes a repository.
Example: Remove-GHRepo dfinke pstest
Deletes a repository workflow.
Example: Remove-GHRepo dfinke pstest basic-powershell.yml
Flag: --trigger
Enables you to manually trigger a workflow. Accepts a workflow configuration file name which MUST be already present on the repository supplied with the -s argument.
Usage: ./bludger.py -s {user_name}/{repo_name} --trigger {template_name}
Example: ./bludger.py -s dfinke/xyz --trigger basic-shell
Function: Stop-GHRun -owner dfinke -repo pstest -runId 559299780
Enables you to stop/cancel a workflow run. Accepts a workflow runId and cancels the workflow.
Example: Stop-GHRun -owner dfinke -repo pstest -runId 559299780
Also, you can pipe Get-GHLatestRun to Stop-GHRun.
Example:
$reponame = 'pstest'
# kick off an infinite loop
Invoke-Advantage dfinke $reponame -template basic-powershell -command 'while(1) {sleep 5}'
# wait till the job is in progress before stopping
do { } until((Get-GHLatestRun dfinke $reponame).status -eq 'in_progress')
Get-GHLatestRun dfinke $reponame | Stop-GHRun
Get-GHLatestRun dfinke $reponamePipe and array of org/repo into Get-GHIssueReport to get this issue report. It retrieves the open and closed issues from repo, calculates the number of days the is was opened, exports it to Excel and creates a pivot table showing how many issues were opened/closed by, year, month, and quarter.
'powershell/powershell','powershell/vscode-powershell','PowerShell/PowerShellEditorServices' | Get-GHIssueReport
Same approach, pipe it to Get-GHPullRequestReport or Get-GHRelease.
Finally you can Get-GHAllReports to get all the above reports.