From 9893b7c086dc5969ce915847fdf7b52607bb3e1e Mon Sep 17 00:00:00 2001 From: "Mikey Lombardi (He/Him)" Date: Thu, 26 Jun 2025 12:11:24 -0500 Subject: [PATCH 1/2] (GHA) Update the auth action to accept an allowlist (#12181) Prior to this change, the verification/`authorization` GitHub Action only supported checking the assigned permissions for a user. This worked for normal accounts. However, the managed bot account for the Learn platform doesn't have permissions for this repository. This change adds a new (backwards-compatible) `authorized_accounts` parameter to the GHA. Repository maintainers can now define an allowlist to use for authorization in addition to the permissions to check. If a user is explicitly in the allowlist, the action skips checking their permissions. If a user isn't in the allowlist, they can still pass authorization if they have matching permissions. --- .../.pwsh/scripts/Test-Authorization.ps1 | 22 +++++++++++++++++-- .../authorization/v1/Parameters.psd1 | 19 ++++++++++++++++ .../verification/authorization/v1/action.yml | 11 ++++++++++ .../verification/authorization/v1/readme.md | 21 +++++++++++++++++- .github/workflows/targeting-valid-branch.yml | 1 + 5 files changed, 71 insertions(+), 3 deletions(-) diff --git a/.github/actions/.pwsh/scripts/Test-Authorization.ps1 b/.github/actions/.pwsh/scripts/Test-Authorization.ps1 index 9d98689fb70e..5263e4d86c1f 100644 --- a/.github/actions/.pwsh/scripts/Test-Authorization.ps1 +++ b/.github/actions/.pwsh/scripts/Test-Authorization.ps1 @@ -69,7 +69,8 @@ param( [Parameter(Mandatory, ParameterSetName='Path')] [string[]]$TargetPath, [ValidateSet('Admin', 'Maintain', 'Pull', 'Push', 'Triage')] - [string[]]$ValidPermissions = @('Admin', 'Maintain') + [string[]]$ValidPermissions = @('Admin', 'Maintain'), + [string[]]$AuthorizedAccounts ) begin { @@ -101,6 +102,10 @@ begin { Console = Format-ConsoleStyle -Text $User -DefinedStyle UserName Markdown = "``$User``" } + AuthorizedAccounts = @{ + Console = Format-ConsoleStyle -Text 'AuthorizedAccounts' -DefinedStyle Success + Markdown = '`AuthorizedAccounts`' + } } if (![string]::IsNullOrEmpty($TargetBranch)) { $ConsoleBranch = Format-ConsoleStyle -Text $TargetBranch -StyleComponent $TargetStyle @@ -123,6 +128,19 @@ begin { } process { + if ($AuthorizedAccounts.Count -gt 0 -and $User -in $AuthorizedAccounts) { + $template = "Account {0} is explicitly permitted per the {1} parameter." + $message = @{ + summary = ($template -f $Texts.Author.Markdown, $Texts.AuthorizedAccounts.Markdown) + console = ($template -f $Texts.Author.Console, $Texts.AuthorizedAccounts.Console) + } + $null = $Summary.AppendLine('## Authorization').AppendLine() + $null = $Summary.AppendLine($message.summary).AppendLine() + # Console Logging + $message.console + + return + } try { $Permissions = Get-AuthorPermission -Owner $Owner -Repo $Repo -Author $User } catch { @@ -149,7 +167,7 @@ process { "$Prefix`t$Setting" } #endregion Permission Retrieval Messaging - + $null = $Summary.AppendLine('## Result').AppendLine() # Check for authorization; if the user has any of the valid permissions, they diff --git a/.github/actions/verification/authorization/v1/Parameters.psd1 b/.github/actions/verification/authorization/v1/Parameters.psd1 index f724b8c7615a..306e47874109 100644 --- a/.github/actions/verification/authorization/v1/Parameters.psd1 +++ b/.github/actions/verification/authorization/v1/Parameters.psd1 @@ -29,6 +29,25 @@ return $Parameters } } + @{ + Name = 'AuthorizedAccounts' + Type = 'String[]' + IfNullOrEmpty = { + param($ErrorTarget) + + # This parameter is optional, so don't error. + } + Process = { + param($Parameters, $Value, $ErrorTarget) + + [string[]]$SpecifiedAccounts = $Value -split ',' + if ($SpecifiedAccounts.Count -gt 0) { + $Parameters.AuthorizedAccounts = $SpecifiedAccounts + Write-HostParameter -Name AuthorizedAccounts -Value $Parameters.AuthorizedAccounts + } + return $Parameters + } + } @{ Name = 'Permissions' diff --git a/.github/actions/verification/authorization/v1/action.yml b/.github/actions/verification/authorization/v1/action.yml index fee05609d9bd..f9f373e7f9b6 100644 --- a/.github/actions/verification/authorization/v1/action.yml +++ b/.github/actions/verification/authorization/v1/action.yml @@ -4,6 +4,16 @@ description: | branch of a repository or to submit a PR editing repo configuration. author: PowerShell Docs Team inputs: + authorized_accounts: + description: | + Defines one or more authorized accounts to skip permission-checking for. This is best used + for bot accounts, which may not have specific permissions to a repository but are used by + the organization's automation. Must be a comma-separated string of account names. + + If a user is in the authorized accounts list, the action skips checking permissions and + passes for that user. + required: false + default: '' permissions: description: | The permissions a user requires to perform a given task. Must be a comma-separated string of @@ -84,6 +94,7 @@ runs: INPUT_PERMISSIONS: ${{ inputs.permissions }} INPUT_TARGET: ${{ inputs.target }} INPUT_USER: ${{ inputs.user }} + INPUT_AUTHORIZED_ACCOUNTS: ${{ inputs.authorized_accounts }} GITHUB_TOKEN: ${{ inputs.token }} run: | Write-Output "::group::Generic Setup" diff --git a/.github/actions/verification/authorization/v1/readme.md b/.github/actions/verification/authorization/v1/readme.md index 2445198e0535..059c2bfd4246 100644 --- a/.github/actions/verification/authorization/v1/readme.md +++ b/.github/actions/verification/authorization/v1/readme.md @@ -54,6 +54,7 @@ jobs: uses: MicrosoftDocs/PowerShell-Docs/.github/actions/verification/authorization/v1@main with: token: ${{ github.token }} + authorized_accounts: 'learn-build-service-prod[bot]' ``` This workflow uses the `pull_request_target` trigger to check whether a Pull Request author is @@ -61,7 +62,10 @@ permitted to submit their Pull Request to the `live` branch. It only runs on Pul target the `live` branch, so other Pull Requests don't get a skipped message for this check. It passes the GitHub token to the action but does not specify a target, relying on the default for -that input, which is the `live` branch. +that input, which is the `live` branch. It does specify that the `learn-build-service-prod[bot]` +managed account is authorized with the `authorized_accounts` parameter. If the account creating a +PR to the `live` branch is the managed account or has either the `Maintain` or `Admin` permission, +the workflow will pass. ### Verifying authorization to change sensitive files @@ -104,6 +108,21 @@ authorization to change files in those paths. ## Inputs +### `authorized_accounts` + +Defines one or more authorized accounts to skip permission-checking for. This is best used for bot +accounts, which may not have specific permissions to a repository but are used by the +organization's automation. Must be a comma-separated string of account names. + +If a user is in the authorized accounts list, the action skips checking permissions and passes for +that user. + +```yaml +required : false +type : string +default : '' +``` + ### `permissions` The permissions a user requires to perform a given task. Must be a comma-separated string of valid diff --git a/.github/workflows/targeting-valid-branch.yml b/.github/workflows/targeting-valid-branch.yml index a27e44405bcb..a84c1345f4e3 100644 --- a/.github/workflows/targeting-valid-branch.yml +++ b/.github/workflows/targeting-valid-branch.yml @@ -23,3 +23,4 @@ jobs: uses: ./.github/actions/verification/authorization/v1 with: token: ${{ github.token }} + authorized_accounts: learn-build-service-prod[bot] From 4cab801c81f4083a5dfc6607e74a5c0d8393c1ae Mon Sep 17 00:00:00 2001 From: Matthew Parsons Date: Thu, 26 Jun 2025 13:37:58 -0700 Subject: [PATCH 2/2] Update using-predictors.md to reference the (now renamed) GA release version of PSResourceGet rather than the old beta version. (#12182) * Update using-predictors.md Fix reference and link from the old v3 module to renamed (release version) PSResource module. Reordered and recommended new module. Slight adjustments to each entry for consistency * Editorial review --------- Co-authored-by: Sean Wheeler --- .../docs-conceptual/learn/shell/using-predictors.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/reference/docs-conceptual/learn/shell/using-predictors.md b/reference/docs-conceptual/learn/shell/using-predictors.md index e3b8601345f0..7f69e2ba1fa2 100644 --- a/reference/docs-conceptual/learn/shell/using-predictors.md +++ b/reference/docs-conceptual/learn/shell/using-predictors.md @@ -40,13 +40,7 @@ pressing the F2 key. You can also use the **PredictionViewStyle** par To use Predictive IntelliSense you must have a newer version of **PSReadLine** installed. For best results, install the latest version of the module. -To install **PSReadLine** using **PowerShellGet**: - -```powershell -Install-Module -Name PSReadLine -``` - -Or install using the new [PowerShellGet v3][05] module: +Install **PSReadLine** using the [Microsoft.PowerShell.PSResourceGet][05] module: ```powershell Install-PSResource -Name PSReadLine @@ -162,7 +156,7 @@ For more information, see [How to create a command-line predictor][02]. [02]: /powershell/scripting/dev-cross-plat/create-cmdline-predictor [03]: https://techcommunity.microsoft.com/t5/azure-tools-blog/announcing-general-availability-of-az-tools-predictor/ba-p/3297956 [04]: https://www.powershellgallery.com/packages/CompletionPredictor -[05]: https://www.powershellgallery.com/packages/PowerShellGet/3.0.14-beta14 +[05]: https://www.powershellgallery.com/packages/Microsoft.PowerShell.PSResourceGet [06]: media/using-predictors/completion-predictor.gif [07]: media/using-predictors/predictor-inline-1.png [08]: media/using-predictors/predictor-listview-1.png