microsoft / psrule.rules.github

A suite of rules to validate GitHub repositories using PSRule.

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.

Module	Description	Downloads / instructions
PSRule.Rules.GitHub	Validate GitHub repositories using PSRule.	latest / instructions

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/[email protected]
      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 [email protected] with any additional questions or comments.

Maintainers

• Bernie White

License

This project is licensed under the MIT License.

psrule.rules.github's Issues

Module not working

Description of the issue

I know it is still a 0.2.0, but would be great if some things already work.
Can't wait till you get this working!

To Reproduce

Steps to reproduce the issue:

Install-Module -Name 'PSRule.Rules.GitHub' -Scope CurrentUser;
Export-GitHubRuleData -Repository dylanprins93/
Assert-PSRule -Module 'PSRule.Rules.GitHub' -InputPath .\*.json -Format File;

Expected behaviour

Well, something...

Error output

Capture any error messages and or verbose messages with -Verbose.

VERBOSE: [PSRule][D] -- Discovering rules in: C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\Baseline.Rule.yaml    
VERBOSE: [PSRule][D] -- Discovering rules in: C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\Config.Rule.yaml      
VERBOSE: [PSRule][D] -- Discovering rules in: C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\Convention.Rule.ps1
VERBOSE: [PSRule][D] -- Found PSRule.Rules.GitHub\GitHub.ExpandRepository in C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\Convention.Rule.ps1
VERBOSE: [PSRule][D] -- Discovering rules in: C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\GitHub.Branch.Rule.ps1
VERBOSE: [PSRule][D] -- Found PSRule.Rules.GitHub\GitHub.Branch.Name in C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\GitHub.Branch.Rule.ps1
VERBOSE: [PSRule][D] -- Discovering rules in: C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\GitHub.Common.Rule.ps1
VERBOSE: [PSRule][D] -- Discovering rules in: C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\GitHub.Repo.Rule.ps1
VERBOSE: [PSRule][D] -- Found PSRule.Rules.GitHub\GitHub.Repo.Protected in C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\GitHub.Repo.Rule.ps1
VERBOSE: [PSRule][D] -- Found PSRule.Rules.GitHub\GitHub.Repo.CodeOfConduct in C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\GitHub.Repo.Rule.ps1
VERBOSE: [PSRule][D] -- Found PSRule.Rules.GitHub\GitHub.Repo.Contributing in C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\GitHub.Repo.Rule.ps1
VERBOSE: [PSRule][D] -- Found PSRule.Rules.GitHub\GitHub.Repo.Readme in C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\GitHub.Repo.Rule.ps1
VERBOSE: [PSRule][D] -- Found PSRule.Rules.GitHub\GitHub.Repo.CodeOwners in C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\GitHub.Repo.Rule.ps1
VERBOSE: [PSRule][D] -- Found PSRule.Rules.GitHub\GitHub.Repo.License in C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\GitHub.Repo.Rule.ps1
VERBOSE: [PSRule][D] -- Found PSRule.Rules.GitHub\GitHub.Repo.Description in C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\GitHub.Repo.Rule.ps1
VERBOSE: [PSRule][D] -- Found PSRule.Rules.GitHub\GitHub.Repo.IssueTempate in C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\GitHub.Repo.Rule.ps1
VERBOSE: [PSRule][D] -- Found PSRule.Rules.GitHub\GitHub.Repo.PRTemplate in C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\GitHub.Repo.Rule.ps1
VERBOSE: [PSRule][D] -- Discovering rules in: C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\Baseline.Rule.yaml    
VERBOSE: [PSRule][D] -- Discovering rules in: C:\Users\DylanPrins\OneDrive - InSpark\Documenten\PowerShell\Modules\PSRule.Rules.GitHub\0.2.0\rules\Config.Rule.yaml      
VERBOSE: [PSRule][R][0][PSRule.Rules.GitHub\GitHub.Branch.Name] :: github-22a87384.json
VERBOSE: [PSRule][R][0][PSRule.Rules.GitHub\GitHub.Repo.Protected] :: github-22a87384.json
VERBOSE: [PSRule][R][0][PSRule.Rules.GitHub\GitHub.Repo.CodeOfConduct] :: github-22a87384.json
VERBOSE: [PSRule][R][0][PSRule.Rules.GitHub\GitHub.Repo.Contributing] :: github-22a87384.json
VERBOSE: [PSRule][R][0][PSRule.Rules.GitHub\GitHub.Repo.Readme] :: github-22a87384.json
VERBOSE: [PSRule][R][0][PSRule.Rules.GitHub\GitHub.Repo.CodeOwners] :: github-22a87384.json
VERBOSE: [PSRule][R][0][PSRule.Rules.GitHub\GitHub.Repo.License] :: github-22a87384.json
VERBOSE: [PSRule][R][0][PSRule.Rules.GitHub\GitHub.Repo.Description] :: github-22a87384.json
VERBOSE: [PSRule][R][0][PSRule.Rules.GitHub\GitHub.Repo.IssueTempate] :: github-22a87384.json
VERBOSE: [PSRule][R][0][PSRule.Rules.GitHub\GitHub.Repo.PRTemplate] :: github-22a87384.json
   WARN  Target object 'github-22a87384.json' has not been processed because no matching rules were found.

Module in use and version:

• Module: PSRule.Rules.GitHub
• Version: [e.g. 0.2.0]

Captured output from $PSVersionTable:

Name                           Value
----                           -----
PSVersion                      7.2.5
PSEdition                      Core
GitCommitId                    7.2.5
OS                             Microsoft Windows 10.0.22000
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

Additional context

Add any other context about the problem here.
github-22a87384.json.txt

Generate a warning or error when data can not be exported

When repository data can not be exported due to authorization a warning or error should be reported but analysis should continue based on any data exported.

Default to the GITHUB_REPOSITORY repository

Use the GITHUB_REPOSITORY environment variable when -Repository is not specified.

GitHub reference

Update PSRule dependency to v1.1.0

Update PSRule module dependency to v1.1.0.

Include labels in the repository object graph

Read and export issue labels and add to the repository object so that rules that query labels can be built.

GitHub API reference

Community profile is null

Description of the issue

Data exported for repository community profile is always null.

Expected behaviour

Community profile should be populated when valid.

Module in use and version:

• Module: PSRule.Rules.GitHub
• Version: v0.1.0-B2103003

Captured output from $PSVersionTable:

Name                           Value
----                           -----
PSVersion                      7.1.3
PSEdition                      Core
GitCommitId                    7.1.3
OS                             Microsoft Windows 10.0.19042
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

Use a CODEOWNERS file

Use a CODEOWNERS file to automatically route reviewer for pull requests.

Add a convention to automatically export repository data

PSRule conventions can be used to export repository data automatically instead of having to call Export-GitHubRuleData directly.

Default branch should be protected

The repository default branch should be protected.

Add resource API versions

From PSRule v1.2.0 onward apiVersion should be set on YAML resources such as Baseline and ModuleConfig. When not set a warning is generated.

Each resource needs to be updated to the apiVersion property.

Forbidden repository protection crashes export

Description of the issue

Export of repository data crashes out if permission is not provided. Some restricted repository information may not be accessible with the default GitHub Actions token or with the provided token.

Expected behaviour

Attempts to export data that is not authorized should not crash the process.

Error output

Capture any error messages and or verbose messages with -Verbose.

ForbiddenException: Resource not accessible by integration
AggregateException: One or more errors occurred. (Resource not accessible by integration)

Bump PSRule dependency to v1.7.0

Bump PSRule dependency to v1.7.0.

Add GitHub Actions documentation

Add example for using with GitHub Actions.

Bump PSRule dependency to v1.3.0

Update PSRule module dependency to v1.3.0.

Export configuration data from repositories

To perform analysis repository configuration data needs to be exported from GitHub APIs.

Export additional repository data

Add support for exporting the following repository data.

• Visibility
• Automatically delete head branches
• Is template flag

Move to Microsoft org

Move this repository under the Microsoft org.

Publish documentation

Update and publish documentation on usage.

Use recommended community files

Public repositories should use recommended community files.

• Description
• Readme
• Code of conduct
• Contributing
• License
• Issue templates
• Pull request templates

Add cmdlet help

Add help for Export-GitHubRuleData cmdlet.

Bump PSRule dependency to v1.2.0

Update PSRule module dependency to v1.2.0.

Extend to Github Enterprise Server

Is your feature request related to a problem? Please describe.

To support Github Enterprise Server

Describe the solution you'd like

Octokit.GithubClient supports both Github and Github Enterprise Server. In theory we should be able to expand with a few more parameters.

https://github.com/octokit/octokit.net/blob/main/docs/getting-started.md#connect-to-github-enterprise

Add publishing for module as NuGet

Add metadata and configure for publishing via NuGet in addition to PowerShell gallery.

Provide configuration for data to export

Currently PSRule tries to export all data related to a repository however some may not be accessible. We should provide a configuration option to allow this to be configured.

Include milestones in the repository object graph

Include milestones for validation in repository object graph.

GitHub API reference

Add code signing and SBOM

Add code signing and SBOM metadata for module.

Check for master branch

Avoid using branch names such as master.

Github action not working

Description of the issue

Thanks for the solution earlier, that works great. I have the same thing with the GitHub actions. It is like its scanning the repository files instead of the GitHub export

To Reproduce

Steps to reproduce the issue:

  test:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v3
    
    # Analyze Azure resources using PSRule for Azure
    - name: Analyze Azure template files
      uses: microsoft/[email protected]
      with:
        modules: 'PSRule.Rules.GitHub'

Expected behaviour

A clear and concise description of what you expected to happen.

Error output

Capture any error messages and or verbose messages with -Verbose.

---
    ____  _____ ____        __
   / __ \/ ___// __ \__  __/ /__
  / /_/ /\__ \/ /_/ / / / / / _ \
 / ____/___/ / _, _/ /_/ / /  __/
/_/    /____/_/ |_|\__,_/_/\___/
Using PSRule v2.2.0+f3d21795d42759a906633118a58cdc088281b9dc
Using PSRule.Rules.GitHub v0.2.0
----------------------------
Explore documentation: https://aka.ms/ps-rule
Contribute and find source: https://github.com/microsoft/PSRule
Report issues: https://github.com/microsoft/PSRule/issues
PSRule.Rules.GitHub: https://github.com/Microsoft/PSRule.Rules.GitHub
----------------------------
From repository: https://github.com/dylanprins93/test
  on : refs/pull/4/merge
  at : a2d[41](https://github.com/dylanprins93/test/runs/7376898849?check_suite_focus=true#step:3:43)897310b1de1fcf17d[49](https://github.com/dylanprins93/test/runs/7376898849?check_suite_focus=true#step:3:51)021ebec63195cd6b
Warning: Using invariant culture may cause rule infomation to be displayed incorrectly. Consider using -Culture or set the Output.Culture option.
Warning: Target object 'test.md' has not been processed because no matching rules were found.
Warning: Target object 'refs/pull/4/merge' has not been processed because no matching rules were found.
Warning: Target object '.github/workflows/psrule.yml' has not been processed because no matching rules were found.
Rules processed: 0, failed: 0, errored: 0
Run dylanprins93/test/268[51](https://github.com/dylanprins93/test/runs/7376898849?check_suite_focus=true#step:3:53)20764 completed in 00:00:00.17682[61](https://github.com/dylanprins93/test/runs/7376898849?check_suite_focus=true#step:3:63)
---

Module in use and version:

• Module: PSRule.Rules.GitHub
• Version: [e.g. 0.2.0]

Captured output from $PSVersionTable:

Additional context

Add any other context about the problem here.

Export additional branch protection data

Add support for exporting the following branch protection data.

• Dismiss stale pull request approvals when new commits are pushed
• Require review from Code Owners
• Required approving reviews