# Technical Documentation: MicrosoftDocs/PowerShell-Docs > ℹ️ **Provenance:** Multi-Tier Ingestion Β· [CodeWiki Reference](https://codewiki.google/github.com/MicrosoftDocs/PowerShell-Docs) ### Overview (`README.md`) --- ms.date: 05/13/2026 --- # PowerShell Documentation Welcome to the PowerShell-Docs repository, the home of the official PowerShell documentation. ## Microsoft Open Source Code of Conduct This project has adopted the [Microsoft Open Source Code of Conduct][04]. ## PowerShell Updatable Help (CabGen) CI Build Status [![Build Status][cabgen-status]][cabgen-log] [cabgen-status]: https://apidrop.visualstudio.com/Content%20CI/_apis/build/status/PROD/CabGen(PowerShell_Updatable_Help)/GitHub_MicrosoftDocs_PowerShell-Docs/6ff7e8c3-dfc6-3ebd-da5a-d5e2ff43de8f_cabgen_Publish-Updatable-Help?repoName=MicrosoftDocs%2FPowerShell-Docs&branchName=live [cabgen-log]: https://apidrop.visualstudio.com/Content%20CI/_build/latest?definitionId=5076&repoName=MicrosoftDocs%2FPowerShell-Docs&branchName=live ## Repository Structure The following list describes the main folders in this repository. ```mermaid --- config: treeView: rowIndent: 20 lineThickness: 2 themeVariables: treeView: labelFontSize: '14px' labelColor: '#3498DB' lineColor: '#3498DB' --- treeView-beta "πŸ“ PowerShell-Docs" "πŸ“ .devcontainer - VS Code Remote Containers configuration" "βš™οΈ .github - GitHub repository configuration and workflows" "πŸ’» .vscode - VS Code settings and recommended extensions" "πŸ“ assets - Downloadable files linked in documentation" "πŸ”€ redir - URL redirection mapping files" "πŸ“š reference - Published documentation content" "πŸ“˜ 5.1 - PowerShell 5.1 cmdlet reference" "πŸ“˜ 7.4 - PowerShell 7.4 cmdlet reference" "πŸ“˜ 7.5 - PowerShell 7.5 cmdlet reference" "πŸ“˜ 7.6 - PowerShell 7.6 cmdlet reference" "πŸ“˜ 7.7 - PowerShell 7.7 cmdlet reference" "🍞 bread - Breadcrumb navigation TOC" "πŸ“– docs-conceptual - Conceptual articles published to learn.ms" "πŸ“„ includes - Markdown include files" "πŸ—ΊοΈ mapping - Version mapping configuration" "πŸ–ΌοΈ media - Images used in documentation" "πŸ“¦ module - Module Browser page source" "πŸ§ͺ tests - Pester tests for build validation" "πŸ”§ tools - Build system tools and scripts" ``` > [!NOTE] > The reference content (in the numbered folders) is used to create the webpages on the Docs site as > well as the updateable help used by PowerShell. The articles in the `docs-conceptual` folder are > only published to the Docs website. ## Contributing We welcome public contributions into this repository via pull requests into the _main_ branch. Please note that before we can accept your pull request you must sign our [Contribution License Agreement][03]. This is a one-time requirement. For more information on contributing, read our [contributor's guide][02]. The contributor's guide contains detailed information about how to contribute documentation, suggested tools, and style and formatting requirements. Please use the Issue and Pull Request templates to help keep documentation consistent across versions. ## Licenses There are two license files for this project. The [MIT License][05] applies to the code contained in this repo. The [Creative Commons license][06] applies to the documentation. [02]: https://aka.ms/PSDocsContributor [03]: https://cla.microsoft.com/ [04]: CODE_OF_CONDUCT.md [05]: LICENSE-CODE.md [06]: LICENSE.md --- ### Overview (`reference/README.md`) --- ms.date: 01/27/2026 title: README --- # PowerShell Reference Reference material is organized into release versions. The content for each version is organized by module name. The `about_*` articles are in an `About` folder under the module folder they're related to. Most of them are under `Microsoft.PowerShell.Core/About`. ## Modules | Module Name / PS Version | 5.1 | 7.4 | 7.5 | 7.6 | | ----------------------------------------- | :---: | :---: | :---: | :---: | | CimCmdlets | X | X | X | X | | ISE (introduced in 2.0) | X | | | | | Microsoft.PowerShell.Archive | X | X | X | X | | Microsoft.PowerShell.Core | X | X | X | X | | Microsoft.PowerShell.Diagnostics | X | X | X | X | | Microsoft.PowerShell.Host | X | X | X | X | | Microsoft.PowerShell.LocalAccounts | X | | | | | Microsoft.PowerShell.Management | X | X | X | X | | Microsoft.PowerShell.ODataUtils | X | | | | | Microsoft.PowerShell.Operation.Validation | X | | | | | Microsoft.PowerShell.Security | X | X | X | X | | Microsoft.PowerShell.Utility | X | X | X | X | | Microsoft.WSMan.Management | X | X | X | X | | PSDiagnostics | X | X | X | X | | PSReadLine | X | X | X | X | | PSScheduledJob | X | | | | | PSWorkflow | X | | | | | PSWorkflowUtility | X | | | | | ThreadJob | | X | X | X | ## History - `PackageManagement` and `PowerShellGet` content moved to the [PowerShell-Docs-PSGet][02] repository. - `PSDesiredStateConfiguration` content moved to the [PowerShell-Docs-DSC][01] repository with the release of PowerShell DSC 2.0. [01]: https://github.com/MicrosoftDocs/PowerShell-Docs-DSC [02]: https://github.com/MicrosoftDocs/PowerShell-Docs-PSGet --- ### Overview (`.github/actions/.pwsh/readme.md`) # Actions PowerShell Code This folder contains the PowerShell used in these actions. The [scripts folder][scripts] holds the actual scripts which are used by the actions. To keep the action definitions relatively minimal and to ensure the code can be tested, documented, and more easily maintained, the functionality of each action is kept in a separate script file. For more information, check that folder's [readme][scripts] or each script's reference documentation in that same folder. The [**gha** module][module] includes helper functions and is only intended to be used by the scripts in this folder. In the future, much of this functionality _may_ be abstracted away into a publicly published module. For more information, see the [module's readme][module] or review the reference documentation for each function. [module]: ./module/readme.md [scripts]: ./scripts/readme.md --- ### Overview (`.github/actions/.pwsh/module/readme.md`) # GHA Module The GitHub Actions (GHA) module includes helper functions for the scripts used by the actions in this repository. Those functions are broken up across broad usage: - API: Functions in the [`api` folder][api-folder] make specific structured calls to GitHub's API with the GitHub CLI (`gh`). Each of these functions performs a very specific query and returns predictably structured data. - Utility: Functions in the [`utility` folder][utility-folder] are more general-purpose and are used by the API functions and the action scripts alike. ## API Functions ### `Add-PullRequestComment` This cmdlet adds a comment to a pull request via GitHub CLI by specifying a raw Markdown string or the path to a Markdown file containing the comment to write. For more information, review the [source code][api-Add-PullRequestComment]. ### `Get-AuthorPermission` This cmdlet retrieves repository permissions for a user, returning a hashtable that enumerates whether the user can admin, maintain, push, triage, and/or pull. For more information, review the [source code][api-Get-AuthorPermission]. ### `Get-OpenPRWithoutExpectation` This cmdlet searches a repository for open pull requests targeting the `main` branch which do not have an expectations comment on them already. It returns a hashtable with the author and number of every pull request in the repository matching these criteria. For more information, review the [source code][api-Get-OpenPRWithoutExpectation] ### `Get-PullRequestChangedFile` This cmdlet retrieves the list of file changes for a PR, returning an array of relative file paths and the change type: `added`, `removed`, `modified`, `renamed`, `copied`, `changed`, or `unchanged`. For more information, review the [source code][api-Get-PullRequestChangedFile] ## Utility Functions ### `Format-ConsoleBoolean` The cmdlet decorates a boolean value for console viewing and returns it. If the **Value** is `$true`, it is returned bright blue. If the **Value** is `$false`, it is returned bright magenta. For more information, review the [source code][utility-Format-ConsoleBoolean] ### `Format-ConsoleStyle` This cmdlet stylizes input text for viewing in the console. For more information, review the [source code][utility-Format-ConsoleStyle] ### `Format-GHAConsoleText` This cmdlet reflows a text string at a specified length for easier console reading. It respects leading whitespace, keeping the indent for wrapped lines. It converts tabs to four spaces for consistency in viewing. It breaks lines on whitespace; not complex, but usually fine in console. Primarily useful for converting error messages into readable lines. For more information, review the [source code][utility-Format-GHAConsoleText] ### `Get-ActionScriptParameter` This cmdlet uses parameter handlers to retrieve and validate the inputs from a GitHub Action, returning a hashtable of parameters to splat on an action script. For more information, review the [source code][utility-Get-ActionScriptParameter] ### `Get-GHAConsoleError` This cmdlet returns an alternate view of an error record for the GH CLI. It limits the object properties to the fully qualified ID, the type of the error, the error message, and the target object (which for GH CLI errors is always the command-line arguments for the failing command). It can retrieve errors from the `$Error` variable or act on an input object. For more information, review the [source code][utility-Get-GHAConsoleError] ### `Get-StaleDocument` This cmdlet searches a specified folder for stale documents as determined by comparing the value of their `ms.date` metadata key with a specified date. By default, any document not updated in the last 330 days is considered stale. It returns the list of stale documents with their **RootPath** (the folder searched recursively), **RelativePath** (the path to the document relative to the **RootPath**), and **MSDate** (the **System.DateTime** value for their `ms.date` property). For more information, review the [source code][utility-Get-StaleDocument]. ### `Get-VersionedContentStatus` This cmdlet returns the change status of versioned content for a pull request. This information can be used to analyze whether a pull request has modified every file it should. Pull requests for versioned content can be tricky, requiring an author to modify the same file in multiple folders. This cmdlet helps clarify if changes have been made across all the versions a file exists in, but does not process the information itself. The output of this cmdlet is an array of objects with the following properties: - **VersionRelativePath**: The path to the changed file from the version folder - **BaseFolder**: The path to the parent folder of multiple versions; the grandparent of the **VersionRelativePath**. - **Versions**: An array of objects representing every version of the content the file exists in. Each entry has a **Version** (like `5.1` or `7.2`) and **ChangeType** (whether the file was `added`, `removed`, `modified`, `renamed`, `copied`, `changed`, or `unchanged`). For more information, review the [source code][utility-Get-VersionedContentStatus] ### `New-CliErrorRecord` This cmdlet generates an error record for a failed `gh` command. It enables the API commands in this module to write useful error messages. The exception type is always **System.ApplicationException** and the error category is always `FromStdErr`. For more information, review the [source code][utility-New-CliErrorRecord] ### `New-InvalidParameterError` This cmdlet composes and returns an error record for when a parameter handler determines that the input for a GitHub Action cannot be validly converted to a parameter for an action script. It returns the error record but does not throw it or write it to the error stream. For more information, review the [source code][utility-New-InvalidParameterError] ### `Write-ActionFailureSummary` Writes a standardized summary entry when a GHA fails due to thrown error. It includes the record of the error in a Markdown codeblock under the heading "Action Failure." For more information, review the [source code][utility-Write-ActionFailureSummary] ### `Write-HostParameter` This cmdlet writes a console log message declaring that a parameter value has been determined, including the name and colorized value. It uses `Write-Host` to avoid polluting the output stream, allowing it to be log this information in parameter handler scriptblocks invoked by the `Get-ActionScriptParameter` cmdlet. For more information, review the [source code][utility-Write-HostParameter] [api-folder]: ./functions/api/ [api-Add-PullRequestComment]: ./functions/api/Add-PullRequestComment.ps1 [api-Get-AuthorPermission]: ./functions/api/Get-AuthorPermission.ps1 [api-Get-OpenPRWithoutExpectation]: ./functions/api/Get-OpenPRWithoutExpectation.ps1 [api-Get-PullRequestChangedFile]: ./functions/api/Get-PullRequestChangedFile.ps1 [utility-folder]: ./functions/utility/ [utility-Format-ConsoleBoolean]: ./functions/utility/Format-ConsoleBoolean.ps1 [utility-Format-ConsoleStyle]: ./functions/utility/Format-ConsoleStyle.ps1 [utility-Format-GHAConsoleText]: ./functions/utility/Format-GHAConsoleText.ps1 [utility-Get-GHAConsoleError]: ./functions/utility/Get-GHAConsoleError.ps1 [utility-Get-ActionScriptParameter]: ./functions/utility/Get-ActionScriptParameter.ps1 [utility-Get-StaleDocument]: ./functions/utility/Get-StaleDocument.ps1 [utility-Get-VersionedContentStatus]: ./functions/utility/Get-VersionedContentStatus.ps1 [utility-New-CliErrorRecord]: ./functions/utility/New-CliErrorRecord.ps1 [utility-New-InvalidParameterError]: ./functions/utility/New-InvalidParameterError.ps1 [utility-Write-ActionFailureSummary]: ./functions/utility/Write-ActionFailureSummary.ps1 [utility-Write-HostParameter]: ./functions/utility/Write-HostParameter.ps1 --- ### Overview (`.github/actions/.pwsh/scripts/readme.md`) # Action Scripts This folder contains the scripts used by the GitHub Actions (GHA). Each script is used by a different action: | Script | Action | | :----------------------------------------- | :------------------------------------------------- | | [Add-Expectations][expectations-script] | [commenting/expectations][expectations-action] | | [Test-Authorization][authorization-script] | [verification/authorization][authorization-action] | | [Test-Checklist][checklist-script] | [verification/checklist][checklist-action] | ## Add-Expectations This script ensures all open community PRs have an expectations comment. It searches the repository for open pull requests without the comment (identified by an HTML comment with a special ID in it) and then checks each open pull request to see if the author is a maintainer or a community member. If the author is a maintainer, the script skips that PR. If the author is a community member, it writes the contents of the message rendered as HTML from Markdown as a comment on the PR. For more information, see [the reference document][expectations-doc]. ## Test-Authorization Checks if a user may perform an action. An author is authorized if they have one or more of the specified permissions. If the author is not authorized, the script (and any GHA workflow calling it) fails. For more information, see [the reference document][authorization-doc]. ## Test-Checklist This script inspects the Markdown body of a Pull Request or GitHub comment to find mandatory checklist items and determine if they are checked or not. It writes console messages and a GitHub summary annotating the findings. If any mandatory checklist items are discovered and not checked, the script throws an exception, failing both the script and associated GitHub Action. To discover mandatory checklist items, it looks for checklist entries that are bolded with double-asterisks and a colon suffix. For example: ```markdown - Not a checklist item - [ ] Not a _mandatory_ checklist item - [ ] **Foo:** a mandatory checklist item that _is not_ checked - [x] **Bar:** a mandatory checklist item that _is_ checked. ``` For more information, see [the reference document][checklist-doc]. [authorization-action]: ../../verification/authorization/v1/readme.md [authorization-doc]: ./Test-Authorization.md [authorization-script]: ./Test-Authorization.ps1 [checklist-action]: ../../verification/checklist/v1/readme.md [checklist-doc]: ./Add-Expectations.md [checklist-script]: ./Add-Expectations.ps1 [expectations-action]: ../../commenting/expectations/v1/readme.md [expectations-doc]: ./Add-Expectations.md [expectations-script]: ./Add-Expectations.ps1 --- ### Overview (`.github/actions/commenting/expectations/v1/readme.md`) # Expectations Writes a comment on newly opened PRs by community members to set their expectations for how the PR review process will proceed. You can specify either a message body in Markdown as input with the **message_body** parameter or specify the path to a Markdown file containing the message body in your repository. In either case, the message _must_ include the following HTML comment somewhere in it: ```html ``` If this comment annotation is not included in the message, the action will not be able to determine whether the comment (or another version of it) has already been added. ## Versioning This action uses a simplified versioning that only tracks major versions. This is the documentation for `v1`. Any _backwards-compatible_ improvements to this action will update this version. If and when the maintainers decide to make a backwards-incompatible change - one that will require manual updates on the part of anyone using this action - we will create a new folder for the next major version, `v2`. We do not have any plans to delete prior versions, but once we move onto a new major version we will not be investing time and effort into updating the older versions. ## Permissions This action requires the following permissions: - **contents:** `read` to inspect the repository and determine whether the Pull Request author is a member of the community or the maintainer team. Anyone who does not have the **Admin** or **Maintain** permission is considered a community member by this action. - **pull-requests:** `write` to add a comment to open Pull Requests by community members. Because this action requires a `write` permission, the `pull_request` trigger will not be able to write any comments if the Pull Request comes from a fork of the repository. If you want to use this action on Pull Requests, you will need to use the `pull_request_target` trigger, which runs in the context of the base branch the Pull Request is targeting and allows the GitHub token to have `write` permissions. Since this action does not use or inspect any of the source files a pull request might change, it does not need to have access to those changes and the `pull_request_target` trigger will be functional for this purpose. Also be aware that whether this action runs on the `pull_request` or `pull_request_target` trigger, the action gets added to the list of checks for that Pull Request. There is currently no way in GitHub to mark an action on those triggers as not being a check of the Pull Request itself. Instead, we suggest that you use this action with the `schedule` trigger to inspect the open Pull Requests in your repository regularly and comment when needed. This means that there will be a delay between when a Pull Request is filed and the comment is added, no additional care needs to be taken with the action and contributors will not see the action in the list of checks on their Pull Request. ## Examples ### Using a Markdown file ```yaml name: Commenting on: schedule: - cron: 0/15 * * * * # run every 15 minutes permissions: contents: read pull-requests: write jobs: Expectations: name: Share Expectations on Community PRs runs-on: windows-latest defaults: run: shell: pwsh steps: - name: Checkout Repository id: checkout_repo uses: actions/checkout@v3 - name: Comment on Community PRs uses: MicrosoftDocs/PowerShell-Docs/.github/actions/commenting/expectations/v1@main with: message_path: .github/messages/expectations.md token: ${{ github.token }} ``` This example workflow uses the `schedule` trigger to run every fifteen minutes. It specifies the minimum permissions needed for this action. For inputs, it specifies the default GitHub token and the path to a Markdown document in the repository which holds the body text to be written as a comment on community Pull Requests. Because it is specifying the path to a document, this workflow also uses the `checkout` action to clone a copy of the repository. This step _must_ happen before the `expectations` action or it will not be able to find the file containing the Markdown. ### Using inline Markdown ```yaml name: Commenting on: schedule: - cron: 0 * * * * permissions: contents: read pull-requests: write jobs: Expectations: name: Share Expectations on Community PRs runs-on: windows-latest defaults: run: shell: pwsh steps: - name: Comment on Community PRs uses: MicrosoftDocs/PowerShell-Docs/.github/actions/commenting/expectations/v1@main with: token: ${{ github.token }} message_body: | # Expectations Thank you for submitting this contribution! Please make sure to read our [style guide][style-guide], fill out the PR checklist, and make sure all tests are passing. If you have any questions or need any help, please ping the maintainers team! We're happy to help. If your work isn't ready for review or merge, please make sure your PR is in draft mode or the title has a `WIP` prefix. [style-guide]: https://docs.contoso.com/project/guide/style ``` This example workflow uses the `schedule` trigger to run at the top of every hour. It specifies the minimum permissions needed for this action. For inputs, it specifies the default GitHub token and the Markdown content to be written as a comment on community Pull Requests. ## Inputs ### `message_body` The message in Markdown to write as the comment body. This input should not be used with **message_path**; if it is, the action will write a warning in the logs and use the **message_body** when commenting on community Pull Requests. ### `message_path` The path to the Markdown file to write as the comment body. This input should not be used with **message_body**; if it is, the action will write a warning in the logs and use the **message_body** when commenting on community Pull Requests. ### `repository` The full name of a repository; to target `https://github.com/MicrosoftDocs/PowerShell-Docs`, the value should be `MicrosoftDocs/PowerShell-Docs`. By default, the value is the repository the _workflow_ is defined in. Unless you are running this action against another repository, you should not need to specify this value. ```yaml required: true type: string default: ${{ github.repository }} ``` ### `token` The `GITHUB_TOKEN` to use to authenticate API calls to verify whether a Pull Request's author is a maintainer or community member and to comment on open community Pull Requests. This **must** be passed to the action. ```yaml required: true type: string default: No ``` --- ### Overview (`.github/actions/reporting/stale-content/v1/readme.md`) # Stale Content Writes a report enumerating stale content in one or more folders of a repository. The report notes the folder, path, and when the document was last updated by folder and subfolder. To determine whether a document is stale, it inspects the `ms.date` key in the document's frontmatter and compares that to a specified date (by default, 330 days before the action runs). By default, this action writes the report in the action's console logs and job summary. You can use the **UploadArtifact** parameter to automatically upload the report as a CSV file as an [artifact][artifacts] automatically, write the report as a CSV to the runner for use in a future step, or use the output data as a variable for a future step in your own workflow. ## Versioning This action uses a simplified versioning that only tracks major versions. This is the documentation for `v1`. Any _backwards-compatible_ improvements to this action will update this version. If and when the maintainers decide to make a backwards-incompatible change - one that will require manual updates on the part of anyone using this action - we will create a new folder for the next major version, `v2`. We do not have any plans to delete prior versions, but once we move onto a new major version we will not be investing time and effort into updating the older versions. ## Permissions This action requires the following permissions: - **contents:** `read` to retrieve information about the changed files to report on. ## Examples ```yml name: Reporting on: schedule: # midnight UTC on the first of every month - cron: 0 0 1 * * permissions: contents: read jobs: Report: name: Stale Content runs-on: windows-latest defaults: run: shell: pwsh steps: - name: Checkout Repository id: checkout_repo uses: actions/checkout@v3 - name: Write Report id: stale_content_report uses: MicrosoftDocs/PowerShell-Docs/.github/actions/reporting/stale-content/v1@main with: relative_folder_path: | reference exclude_folder_segment: | lang-spec media samples upload_artifact: true ``` This example workflow uses the `schedule` trigger to run at midnight on the first of every month. It specifies the minimum permissions needed for this action. For inputs, it specifies that the action should: - only search the `reference` folder in the project root for stale documents - ignore any files whose parent path includes a folder named `lang-spec`, `media`, or `samples` - export the report as a comma-separated-values (CSV) file and upload it as an action artifact It searches every file in the `reference` folder (except for those excluded) for any files where the `ms.date` metadata key's value is a date older than 330 days from the time the action runs. It then writes a report by folder and subfolder in the action's console logs and Markdown summary before exporting the data as a CSV and uploading it as a GitHub Action artifact named `StaleContentReport`. The output below is an example of how it renders the stale document report in Markdown. > ### Stale Content Report > > Documents in this report are stale since 8/15/2021 12:00:00 AM > > | Relative Root Folder Path | Stale Articles | > | :------------------------ | :------------: | > | reference/docs-conceptual | 39 | > > #### reference/docs-conceptual > > ##### community > > | File Name | Last Updated On | > | :-------- | :-------------: | > | community-support.md | 04/29/2020 | ## Inputs ### `relative_folder_path` Specify the path to the folder or folders to recursively search for stale documents, relative to the root of the repository. If not specified, the default value is the repository's root folder. To specify multiple folders, separate each folder by a newline in a multiline string block in yaml, like this: ```yaml name: Stale Content Report uses: MicrosoftDocs/PowerShell-Docs/.github/actions/reporting/stale-content/v1@main with: relative_folder_path: | reference/conceptual reference/contribution ``` In this example, only the `reference/conceptual` and `reference/contribution` folders in the root folder for the repository are inspected for stale documentation. ```yaml required: false type: string default: no ``` ### `exclude_folder_segment` Specify one or more complete folder segments as strings to exclude from the list of files to report on. Any file whose path case-insensitively matches an excluded segment are discarded from the list before inspection. To specify multiple folders, separate each folder by a newline in a multiline string block in yaml, like this: ```yaml name: Stale Content Report uses: MicrosoftDocs/PowerShell-Docs/.github/actions/reporting/stale-content/v1@main with: exclude_folder_segment: | archived release-notes ``` In this example, any documents in folders named `archived` and `release-notes` are ignored during inspection, regardless of the rest of their root path or how nested they are. So the files in the folders `reference/archived/v1/`, `reference/foo/release-notes/`, and 'reference/bar/release-notes' would be ignored, but not files in `reference/baz/release/notes` or the `reference/archived.md` file. ```yaml required: false type: string default: no ``` ### `days_until_stale` Specify an integer representing how many days can pass before a document is considered stale. If any document's `ms.date` key is older than this value, it is returned as a stale document. If used with the **stale_since_date** parameter, this value is ignored and the action emits a warning.If neither this parameter nor **stale_since_date** are specified, the action treats files with an `ms.date` value older than 330 days from when the action is run as stale. ```yaml required: false type: int default: no ``` ### `stale_since_date` Specify an [ISO 8601][iso-8601] date-time string representing the point at which any older documents are considered stale. If any document's `ms.date` key is older than this value, it is returned as a stale document. If used with the **days_until_stale** parameter, this value is used and the action emits a warning. If neither this parameter nor **days_until_stale** are specified, the action treats files with an `ms.date` value older than 330 days from when the action is run as stale. ```yaml required: false type: string default: no ``` ### `upload_artifact` Specify as `true` to upload the CSV of the report as an [action artifact][artifacts]. If this parameter is not specified or is specified as anything other than `true` (case-insensitive), the action does not automatically upload the report as an artifact. This parameter implies the use of **export_as_csv**, you do not need to specify them together. If this action is used to upload the report as an artifact, it does so with the name of the artifact set to the same value as the path to the CSV file (see the **export_path** parameter) with the default retention period. For more control over how reports are uploaded, consider using the [actions/upload-artifact][artifact-action] action directly, like so: ```yaml - name: Stale Content Report uses: MicrosoftDocs/PowerShell-Docs/.github/actions/reporting/stale-content/v1@main with: export_as_csv: true export_path: report.csv - name: Upload Stale Content Report uses: actions/upload-artifact@v3 with: name: stale-report path: report.csv retention-days: 30 ``` This example uses this action to generate a stale content report CSV file and then uses the `actions/upload-artifact` action separately to upload the artifact with workflow-defined name (`stale-report`) and retention period (`30` days). ```yaml required: false type: boolean default: no ``` ### `export_as_csv` Specify as `true` to export the stale content report as a comma-separated values (CSV) file. If this parameter is not specified or is specified as anything other than `true` (case-insensitive), the action does not export the report. It still writes the report in the console logs and Markdown summary for the workflow. Using the **upload_artifact** parameter implies this parameter. You do not need to specify them together. By default, the report is exported to the project root as `StaleContentReport.<%Y-%m-%d>.csv`, where `<%Y-%m-%d>` is the date the action is run. For example, if run on July 12 2022, the filename is `StaleContentReport.2022-07-12.csv`. Use the **export_path** parameter to set a different path or name for the report. ```yaml required: false type: boolean default: no ``` ### `export_path` Specify the path to where the CSV file should be written. This parameter is only valid with the **UploadArtifact** or **ExportAsCsv** parameters. If used without them, the value is ignored. ```yaml required: false type: string default: no ``` [artifact-action]: https://github.com/actions/upload-artifact [artifacts]: https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts [iso-8601]: https://www.iso.org/iso-8601-date-and-time-format.html --- ### Overview (`.github/actions/reporting/versioned-content/v1/readme.md`) # Versioned Content Writes a report on the changes to versioned content in a repository by Pull Request. The report summarizes how many changes in the Pull Request were to versioned content and writes tables enumerating every changed file by folder and how, if at all, the Pull Request modified each file by version. ## Versioning This action uses a simplified versioning that only tracks major versions. This is the documentation for `v1`. Any _backwards-compatible_ improvements to this action will update this version. If and when the maintainers decide to make a backwards-incompatible change - one that will require manual updates on the part of anyone using this action - we will create a new folder for the next major version, `v2`. We do not have any plans to delete prior versions, but once we move onto a new major version we will not be investing time and effort into updating the older versions. ## Permissions This action requires the following permissions: - **contents:** `read` to retrieve information about the changed files to report on. ## Examples ```yml name: Reporting on: pull_request: branches: - main paths: - reference permissions: contents: read jobs: Report: name: Versioned Content runs-on: windows-latest defaults: run: shell: pwsh steps: - name: Write Report id: versioned_content_report uses: MicrosoftDocs/PowerShell-Docs/.github/actions/reporting/versioned-content/v1@main with: token: ${{ github.token }} include_path_pattern: | ^reference exclude_path_pattern: | archive\/ ``` This workflow uses the `pull_request` trigger to report on changes to versioned content in the Pull Request. It only runs on Pull Requests targeting the `main` branch which change at least one file in the `reference` folder. When the Pull Request meets those criteria, this action is called. It retrieves the list of changes for the Pull Request. Before it does anything else, it filters the changed files because of the use of the **include_path_pattern** and **exclude_path_pattern** inputs. First, it filters the list of files to only include those whose path starts with `reference`. After the list is filtered by the include pattern, it is filtered again to exclude any files with a folder segment ending in `archive`. After the list of changes is filtered, it searches those changes to find ones to versioned content, as identified by the inclusion of a version for a folder name. It then processes the versioned content and the rest of the files to correlate every version of an identically-named file together and write a report for every folder with modified versioned content, enumerating how the file was modified (if at all) across the versions. The output below is an example of how it renders the changeset for files by folder and version. > ### Change Sets for `Microsoft.PowerShell.Archive` > > | Version-Relative Path | 5.1 | 7.0 | 7.1 | 7.2 | 7.3 | > |:----------------------------------|:----------:|:----------:|:-------:|:----------:|:---------:| > | `Compress-Archive.md` | Unchanged | Unchanged | Removed | Unchanged | Unchanged | > | `Expand-Archive.md` | Unchanged | Unchanged | Removed | Unchanged | Unchanged | > | `Microsoft.PowerShell.Archive.md` | Unchanged | Unchanged | Removed | Unchanged | Unchanged | ## Inputs ### `exclude_path_pattern` Regular expression patterns to compare to the changed content file paths. Only changes whose path matches _none_ of the specified patterns are included in the report. To specify multiple patterns, separate each branch by a newline in a multiline string block in yaml, like this: ```yaml name: Versioned Content Report uses: MicrosoftDocs/PowerShell-Docs/.github/actions/reporting/versioned-content/v1@main with: exclude_path_pattern: | ^reference\/ AlwaysReport ``` Any changes to file paths matching `^reference\/` (anything under the `reference` folder in the repository's root folder) or `AlwaysReport` (any file in the repository with that text in its path) is excluded from the report. ```yaml required: false type: string default: no ``` ### `include_path_pattern` Regular expression patterns to compare to the changed content file paths. Only changes whose path matches one or more of the specified patterns are included in the report. To specify multiple patterns, separate each branch by a newline in a multiline string block in yaml, like this: ```yaml name: Versioned Content Report uses: MicrosoftDocs/PowerShell-Docs/.github/actions/reporting/versioned-content/v1@main with: include_path_pattern: | ^reference\/ AlwaysReport ``` Only changes to file paths matching `^reference\/` (anything under the `reference` folder in the repository's root folder) and `AlwaysReport` (any file in the repository with that text in its path) is included in the report. ```yaml required: false type: string default: no ``` ### `number` The numerical ID of the PR to check for versioned content. By default, this action uses the number for the current Pull Request if the calling workflow is triggered by the `pull_request` or `pull_request_target` event. ```yaml required: true type: int default: ${{ github.event.pull_request.number }} ``` ### `repository` The full name of a repository; to target `https://github.com/MicrosoftDocs/PowerShell-Docs`, the value should be `MicrosoftDocs/PowerShell-Docs`. By default, the value is the repository the _workflow_ is defined in. Unless you are running this action against another repository, you should not need to specify this value. ```yaml required: true type: string default: ${{ github.repository }} ``` ### `token` The GITHUB_TOKEN to use to authenticate API calls to retrieve the changes a Pull Request makes. This **must** be passed to the action. ```yaml required: true type: string default: no ``` --- ### Overview (`.github/actions/verification/authorization/v1/readme.md`) # Authorization Checks to see whether a user may perform a certain action. For example, to target the `live` branch of a repository or to submit a PR editing repository configuration. ## Versioning This action uses a simplified versioning that only tracks major versions. This is the documentation for `v1`. Any _backwards-compatible_ improvements to this action will update this version. If and when the maintainers decide to make a backwards-incompatible change - one that will require manual updates on the part of anyone using this action - we will create a new folder for the next major version, `v2`. We do not have any plans to delete prior versions, but once we move onto a new major version we will not be investing time and effort into updating the older versions. ## Permissions This action requires the following permissions: - **metadata:** `read` to inspect the repository and determine the permissions of a user for that repository. Unfortunately, GitHub Actions does not allow a workflow author to specify **metadata** in the list of permissions for a job or step. It does however allow you to specify **contents**, which seems to enable the same behavior while minimizing the risk. Note that the `pull_request` trigger will not be able to retrieve the permissions of users if the Pull Request comes from a fork of the repository. If you want to use this action on Pull Requests, you must use the `pull_request_target` trigger, which runs in the context of the base branch the Pull Request is targeting and allows the GitHub token to retrieve those permissions. ## Examples ### Verifying authorization to target a branch ```yaml name: Authorization on: pull_request_target: branches: - live permissions: contents: read jobs: Test: name: Check Branch Permissions runs-on: windows-latest defaults: run: shell: pwsh steps: - name: Authorized to Target Live Branch? 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 permitted to submit their Pull Request to the `live` branch. It only runs on Pull Requests which 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. 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 ```yaml name: Authorization on: pull_request_target: branches: - main paths: - .github/workflows/** permissions: contents: read jobs: Test: name: Check Repo File Permissions runs-on: windows-latest defaults: run: shell: pwsh steps: - name: Authorized to Modify Repo Files? uses: ./.github/actions/verification/authorization/v1 with: token: ${{ github.token }} permissions: Maintain,Admin target: path:.github/workflows/ ``` This workflow uses the `pull_request_target` trigger to checker whether a Pull Request author is permitted to submit a Pull Request that modifies files in the `.github/workflows` or `.config` folders. It only runs on Pull Requests which modify files in those folders, so other Pull Requests don't get a skipped message for this check. It passes the GitHub token to the action and specifies that it requires the user to have the `Maintain` or `Admin` permissions. Because GitHub Actions cannot have arrays as input, the input needed to be specified as a comma-separated string. Finally, it specifies the **target** as `path:.github/workflows/,.config/`. The `path:` prefix tells the action to write a message about 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 permissions. Valid permissions are (case-insensitive): - `Admin` - `Maintain` - `Pull` - `Push` - `Triage` If a user has _any_ of the specified permissions, they are authorized. ```yaml required: true type: string default: Admin,Maintain ``` ### `repository` The full name of a repository; to target `https://github.com/MicrosoftDocs/PowerShell-Docs`, the value should be `MicrosoftDocs/PowerShell-Docs`. By default, the value is the repository the _workflow_ is defined in. Unless you are running this action against another repository, you should not need to specify this value. ### `target` The branches or globbed file paths to verify authorization to target for changes. To specify a branch, type a string like `branch:live`. This value determines the messaging for this action but does not limit the authorization status check. To ensure your authorization workflow only runs when a branch is targeted, use the **branches** setting for the `pull_request` or `pull_request_target` trigger. To ensure your authorization workflow only runs when a Pull Request modifies particular files, use the **paths** setting for the `pull_request` or `pull_request_target` trigger. You can use those settings together. For more information, see the documentation for the [branches][syntax-docs-branches] and [paths][syntax-docs-paths] settings for workflows in GitHub's documentation. To specify multiple branches, separate each branch by a comma and/or newline, like `branch: live, production`. To specify a filepath, specify one or more path separated by a comma and/or a newline, like `path: foo/**/*.md, bar/*.json`. If you do not specify a prefix like `branch:` or `path:` or specify an invalid prefix, it will be interpreted as branch. The default is `branch:live`. When using multiple values, it can be easier to type them in a multiline string block in yaml, like this: ```yaml name: Authorized to Modify Repo Files? uses: MicrosoftDocs/PowerShell-Docs/.github/actions/verification/authorization/v1@main with: target: | path: *.config.json first/folder/path another/path final/path/entry/*.jsonc ``` ```yaml required: true type: string default: branch:live ``` ### `token` The GITHUB_TOKEN to use to authenticate API calls to verify the user's permissions for the repository. This **must** be passed to the action. ```yaml required: true type: string default: no ``` ### `user` The GitHub login ID to check permissions for. By default, the value is the author of the Pull Request when the workflow uses the `pull_request` or `pull_request_target` trigger. For any other trigger, you will need to specify this value. ```yaml required: true type: string default: ${{ github.event.pull_request.user.login }} ``` [syntax-docs-branches]: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore [syntax-docs-paths]: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore --- ### Overview (`.github/actions/verification/checklist/v1/readme.md`) # Checklist Inspects the checklist items on a pull request to see if they have all been filled out. It only looks for mandatory checklist items. If any mandatory checklist items are not checked, the action fails. It writes a summary and console logs indicating which mandatory checklist items were not checked. To be interpreted by this action as mandatory checklist items, they must be formatted in Markdown to follow a specific syntax: ```markdown - [ ] **Item Name:** Explanation of the item` ``` To be recognized as a mandatory checklist item by this action, the item must: - use valid syntax for checklists on GitHub (i.e. `- [ ]` for an unchecked item and `- [x]` for a checked item) - immediately follow the checklist syntax with a single space and then two asterisks (`**`) - include one or more characters, specifying the name of the mandatory checklist item - close the name of the item with a colon followed by two asterisks (`:**`) Including explanatory text after the mandatory checklist item declaration is strictly optional but strongly encouraged. This example code block illustrates how this action parses Markdown and what is interpreted as a valid mandatory checklist item for this action to verify: ```markdown A paragraph is not a checklist item - This is a list item, but not a checklist item. - [ ] This is a checklist item, but not mandatory. - [ ] Not Bold: This is a checklist item, but not recognized as mandatory. - [ ] **Colon Outside**: This is a checklist item, but not recognized as mandatory. - [ ] **Foo:** This is a mandatory checklist item named `Foo`. It is not checked. - [x] **Bar:** This is a mandatory checklist item named `Bar`. It is checked. ``` ## Versioning This action uses a simplified versioning that only tracks major versions. This is the documentation for `v1`. Any _backwards-compatible_ improvements to this action will update this version. If and when the maintainers decide to make a backwards-incompatible change - one that will require manual updates on the part of anyone using this action - we will create a new folder for the next major version, `v2`. We do not have any plans to delete prior versions, but once we move onto a new major version we will not be investing time and effort into updating the older versions. ## Permissions This action requires no read or write permissions as long as it is used with the `pull_request` or `pull_request_target` trigger because the necessary information is included in the event payload for those triggers. ## Examples ```yml name: Checklist on: pull_request: branches: - main types: - opened - reopened - ready_for_review - edited - synchronize permissions: contents: read jobs: Test: name: Verify Status runs-on: windows-latest if: | !contains(github.event.pull_request.title, 'WIP') && !github.event.pull_request.draft defaults: run: shell: pwsh steps: - name: Verify Checklist id: verify_checklist uses: MicrosoftDocs/PowerShell-Docs/.github/actions/verification/checklist/v1@main ``` This workflow uses the `pull_request` trigger to verify whether the checklist included in the Pull Request template has been filled out. It only runs on Pull Requests targeting the `main` branch when they are opened, reopened, specifically request a review, the body is edited, or the author updates their Pull Request (as with a force push). The job only runs if the title of the Pull Request does not include `WIP` anywhere in it and the Pull Request is not marked as a draft - if it's WIP or a draft, there's no reason to verify the checklist because the Pull Request is not ready for final review or merge. When the Pull Request meets those criteria, this action is called and it inspects the body of the Pull Request to discover any mandatory checklist items. It then reports whether those items are checked or not. If any mandatory checklist items are not checked, the action fails with an error, reporting which mandatory items have not yet been checked. ## Inputs ### `body` The body of the GitHub Pull Request to inspect for checklist completion. If using this action on a `pull_request` or `pull_request_target` event, this is handled automatically. Otherwise, it must be specified. ```yaml required: true type: string default: ${{ github.event.pull_request.body }} ``` ### `pull_request_url` The URL of the GitHub Pull Request, issue, discussion, or comment to inspect for checklist completion. If using this action on a `pull_request` or `pull_request_target` event, this is handled automatically. Otherwise, it must be specified. ```yaml required: true type: string default: ${{ github.event.pull_request.url }} ``` --- --- METRICS --- - Files Extracted: 10 - Estimated Token Budget: ~13202 tokens - Canonical Reference: https://codewiki.google/github.com/MicrosoftDocs/PowerShell-Docs