PSRule for GitHub

A suite of rules to validate GitHub repositories using PSRule.

Features of PSRule for GitHub include:

• Ready to go - Leverage pre-built rules.
• DevOps - Validate repositories throughout their lifecycle.
• Cross-platform - Run with GitHub Actions or other CI integrations.

Support

This project uses GitHub Issues to track bugs and feature requests. Please search the existing issues before filing new issues to avoid duplicates.

• For new issues, file your bug or feature request as a new issue.
• For help, discussion, and support questions about using this project, join or start a discussion.

If you have any problems with the PSRule engine, please check the project GitHub issues page instead.

Support for this project/ product is limited to the resources listed above.

Getting the modules

This project requires the PSRule PowerShell module. For details on each see install.

You can download and install these modules from the PowerShell Gallery.

Getting started

Using with GitHub Actions

The following example shows how to setup GitHub Actions to validate GitHub repositories.

1. See [Creating a workflow file][create-workflow].
2. Reference microsoft/ps-rule with modules: 'PSRule.Rules.GitHub'.

For example:

# Example: .github/workflows/analyze-gh.yaml

#
# STEP 1: Repository validation
#
name: Analyze repository
on:
- push
jobs:
  analyze_arm:
    name: Analyze repository
    runs-on: ubuntu-latest
    steps:

    - name: Checkout
      uses: actions/checkout@v4

    # STEP 2: Run analysis against exported data
    - name: Analyze repository
      uses: microsoft/ps-rule@v2.9.0
      with:
        modules: 'PSRule.Rules.GitHub'

Using locally

The following example shows how to setup PSRule locally to validate templates pre-flight.

1. Install the PSRule.Rules.GitHub module and dependencies from the PowerShell Gallery.
2. Export repository data for analysis.
3. Run analysis against a GitHub repository.

For example:

# STEP 1: Install PSRule.Rules.GitHub from the PowerShell Gallery
Install-Module -Name 'PSRule.Rules.GitHub' -Scope CurrentUser;

# STEP 2: Export repository configuration data for microsoft/PSRule
Export-GitHubRuleData -Repository 'microsoft/PSRule';

# STEP 3: Run analysis against exported data
Assert-PSRule -Module 'PSRule.Rules.GitHub' -InputPath './*.json';

The Export-GitHubRuleData cmdlet exports repository data to JSON. To export multiple repositories:

• Comma separate each repository.
• Use <organization>/ to include all repositories in the organization.

Authenticate to export private repositories by:

• Using -Credential to specify a PSCredential object with a personal access token (PAT). The username of PSCredential is ignored.
• Using -UseGitHubToken to read a PAT token from the GITHUB_TOKEN environment variable.

For advanced usage, see Assert-PSRule help.

Rule reference

For a list of rules included in the PSRule.Rules.GitHub module see:

• Rules by category

Language reference

PSRule for GitHub extends PowerShell with the following features.

Commands

The following commands exist in the PSRule.Rules.GitHub module:

• Export-GitHubRuleData - Export GitHub repository configuration.

Changes and versioning

Modules in this repository will use the semantic versioning model to declare breaking changes from v1.0.0. Prior to v1.0.0, breaking changes may be introduced in minor (0.x.0) version increments. For a list of module changes please see the change log.

Pre-release module versions are created on major commits and can be installed from the PowerShell Gallery. Pre-release versions should be considered experimental. Modules and change log details for pre-releases will be removed as standard releases are made available.

Contributing

This project welcomes contributions and suggestions. If you are ready to contribute, please visit the contribution guide.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Maintainers

• Bernie White

License

This project is licensed under the MIT License.