PowerShell-Docs Documentation

The official PowerShell documentation sources

2,564 stars PowerShell PowerShell 1 file · ~13,291 tokens #hacktoberfest#powershell#powershell-documentation
RAW Doc

Technical Documentation: MicrosoftDocs/PowerShell-Docs

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

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.

PowerShell Updatable Help (CabGen) CI Build Status

Build Status

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. This is a one-time requirement.

For more information on contributing, read our contributor's guide. 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 applies to the code contained in
this repo. The Creative Commons license applies to the documentation.

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
    repository.
  • PSDesiredStateConfiguration content moved to the PowerShell-Docs-DSC repository with the
    release of PowerShell DSC 2.0.

Overview (`.github/actions/.pwsh/readme.md`)

Actions PowerShell Code

This folder contains the PowerShell used in these actions.

The scripts folder 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 or each script's reference documentation in
that same folder.

The gha 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 or review the
reference documentation for each function.

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 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 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.

`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.

`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

`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

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

`Format-ConsoleStyle`

This cmdlet stylizes input text for viewing in the console.

For more information, review the source code

`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

`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

`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

`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.

`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

`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

`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

`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

`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

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 commenting/expectations
Test-Authorization verification/authorization
Test-Checklist verification/checklist

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.

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.

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.

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 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 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. 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 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

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 and
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 }}

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 ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#hacktoberfest Browse hacktoberfest catalog → #powershell Browse powershell catalog → #powershell-documentation Browse powershell-documentation catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →