workflow.yml

name: Process-PSModule

on:
  workflow_call:
    secrets:
      APIKey:
        description: The API key for the PowerShell Gallery.
        required: true
      TEST_APP_ENT_CLIENT_ID:
        description: The client ID of an Enterprise GitHub App for running tests.
        required: false
      TEST_APP_ENT_PRIVATE_KEY:
        description: The private key of an Enterprise GitHub App for running tests.
        required: false
      TEST_APP_ORG_CLIENT_ID:
        description: The client ID of an Organization GitHub App for running tests.
        required: false
      TEST_APP_ORG_PRIVATE_KEY:
        description: The private key of an Organization GitHub App for running tests.
        required: false
      TEST_USER_ORG_FG_PAT:
        description: The fine-grained personal access token with org access for running tests.
        required: false
      TEST_USER_USER_FG_PAT:
        description: The fine-grained personal access token with user account access for running tests.
        required: false
      TEST_USER_PAT:
        description: The classic personal access token for running tests.
        required: false
    inputs:
      SettingsPath:
        type: string
        description: The path to the settings file. Settings in the settings file take precedence over the action inputs.
        required: false
        default: .github/PSModule.yml
      Debug:
        type: boolean
        description: Enable debug output.
        required: false
        default: false
      Verbose:
        type: boolean
        description: Enable verbose output.
        required: false
        default: false
      Version:
        type: string
        description: Specifies the version of the GitHub module to be installed. The value must be an exact version.
        required: false
        default: ''
      Prerelease:
        type: boolean
        description: Whether to use a prerelease version of the 'GitHub' module.
        required: false
        default: false
      WorkingDirectory:
        type: string
        description: The path to the root of the repo.
        required: false
        default: '.'

permissions:
  contents: write      # to checkout the repo and create releases on the repo
  pull-requests: write # to write comments to PRs
  statuses: write      # to update the status of the workflow from linter
  pages: write         # to deploy to Pages
  id-token: write      # to verify the deployment originates from an appropriate source

jobs:
  # Runs on:
  # - ✅ Open/Updated PR - Always runs to load configuration
  # - ✅ Merged PR       - Always runs to load configuration
  # - ✅ Abandoned PR    - Always runs to load configuration
  # - ✅ Manual run      - Always runs to load configuration
  Get-Settings:
    uses: ./.github/workflows/Get-Settings.yml
    with:
      SettingsPath: ${{ inputs.SettingsPath }}
      Debug: ${{ inputs.Debug }}
      Prerelease: ${{ inputs.Prerelease }}
      Verbose: ${{ inputs.Verbose }}
      Version: ${{ inputs.Version }}
      WorkingDirectory: ${{ inputs.WorkingDirectory }}

  # Runs on:
  # - ✅ Open/Updated PR - Lints code changes in active PRs
  # - ❌ Merged PR       - No need to lint after merge + its a merge commit that causes issues with super-linter
  # - ❌ Abandoned PR    - No need to lint abandoned changes
  # - ❌ Manual run      - Only runs for PR events
  Lint-Repository:
    if: fromJson(needs.Get-Settings.outputs.Settings).Run.LintRepository
    needs:
      - Get-Settings
    uses: ./.github/workflows/Lint-Repository.yml
    with:
      Settings: ${{ needs.Get-Settings.outputs.Settings }}

  # Runs on:
  # - ✅ Open/Updated PR - Builds module for testing
  # - ✅ Merged PR       - Builds module for publishing
  # - ❌ Abandoned PR    - Skips building abandoned changes
  # - ✅ Manual run      - Builds module when manually triggered
  Build-Module:
    if: fromJson(needs.Get-Settings.outputs.Settings).Run.BuildModule
    uses: ./.github/workflows/Build-Module.yml
    needs:
      - Get-Settings
    with:
      Settings: ${{ needs.Get-Settings.outputs.Settings }}

  # Runs on:
  # - ✅ Open/Updated PR - Tests source code changes
  # - ✅ Merged PR       - Tests source code before publishing
  # - ❌ Abandoned PR    - Skips testing abandoned changes
  # - ✅ Manual run      - Tests source code when manually triggered
  Test-SourceCode:
    if: fromJson(needs.Get-Settings.outputs.Settings).Run.TestSourceCode
    needs:
      - Get-Settings
    uses: ./.github/workflows/Test-SourceCode.yml
    with:
      Settings: ${{ needs.Get-Settings.outputs.Settings }}

  # Runs on:
  # - ✅ Open/Updated PR - Lints source code changes
  # - ✅ Merged PR       - Lints source code before publishing
  # - ❌ Abandoned PR    - Skips linting abandoned changes
  # - ✅ Manual run      - Lints source code when manually triggered
  Lint-SourceCode:
    if: fromJson(needs.Get-Settings.outputs.Settings).Run.LintSourceCode
    needs:
      - Get-Settings
    uses: ./.github/workflows/Lint-SourceCode.yml
    with:
      Settings: ${{ needs.Get-Settings.outputs.Settings }}

  # Runs on:
  # - ✅ Open/Updated PR - Tests built module
  # - ✅ Merged PR       - Tests built module before publishing
  # - ❌ Abandoned PR    - Skips testing abandoned changes
  # - ✅ Manual run      - Tests built module when manually triggered
  Test-Module:
    if: fromJson(needs.Get-Settings.outputs.Settings).Run.TestModule && needs.Build-Module.result == 'success' && !cancelled()
    needs:
      - Build-Module
      - Get-Settings
    uses: ./.github/workflows/Test-Module.yml
    with:
      Settings: ${{ needs.Get-Settings.outputs.Settings }}

  # Runs on:
  # - ✅ Open/Updated PR - Runs setup scripts before local module tests
  # - ✅ Merged PR       - Runs setup scripts before local module tests
  # - ❌ Abandoned PR    - Skips setup for abandoned changes
  # - ✅ Manual run      - Runs setup scripts when manually triggered
  BeforeAll-ModuleLocal:
    if: fromJson(needs.Get-Settings.outputs.Settings).Run.BeforeAllModuleLocal && needs.Build-Module.result == 'success' && !cancelled()
    uses: ./.github/workflows/BeforeAll-ModuleLocal.yml
    secrets:
      TEST_APP_ENT_CLIENT_ID: ${{ secrets.TEST_APP_ENT_CLIENT_ID }}
      TEST_APP_ENT_PRIVATE_KEY: ${{ secrets.TEST_APP_ENT_PRIVATE_KEY }}
      TEST_APP_ORG_CLIENT_ID: ${{ secrets.TEST_APP_ORG_CLIENT_ID }}
      TEST_APP_ORG_PRIVATE_KEY: ${{ secrets.TEST_APP_ORG_PRIVATE_KEY }}
      TEST_USER_ORG_FG_PAT: ${{ secrets.TEST_USER_ORG_FG_PAT }}
      TEST_USER_USER_FG_PAT: ${{ secrets.TEST_USER_USER_FG_PAT }}
      TEST_USER_PAT: ${{ secrets.TEST_USER_PAT }}
    needs:
      - Build-Module
      - Get-Settings
    with:
      Settings: ${{ needs.Get-Settings.outputs.Settings }}

  # Runs on:
  # - ✅ Open/Updated PR - Tests module in local environment
  # - ✅ Merged PR       - Tests module in local environment before publishing
  # - ❌ Abandoned PR    - Skips testing abandoned changes
  # - ✅ Manual run      - Tests module in local environment when manually triggered
  Test-ModuleLocal:
    if: fromJson(needs.Get-Settings.outputs.Settings).Run.TestModuleLocal && needs.Build-Module.result == 'success' && !cancelled()
    needs:
      - Build-Module
      - Get-Settings
      - BeforeAll-ModuleLocal
    uses: ./.github/workflows/Test-ModuleLocal.yml
    secrets:
      TEST_APP_ENT_CLIENT_ID: ${{ secrets.TEST_APP_ENT_CLIENT_ID }}
      TEST_APP_ENT_PRIVATE_KEY: ${{ secrets.TEST_APP_ENT_PRIVATE_KEY }}
      TEST_APP_ORG_CLIENT_ID: ${{ secrets.TEST_APP_ORG_CLIENT_ID }}
      TEST_APP_ORG_PRIVATE_KEY: ${{ secrets.TEST_APP_ORG_PRIVATE_KEY }}
      TEST_USER_ORG_FG_PAT: ${{ secrets.TEST_USER_ORG_FG_PAT }}
      TEST_USER_USER_FG_PAT: ${{ secrets.TEST_USER_USER_FG_PAT }}
      TEST_USER_PAT: ${{ secrets.TEST_USER_PAT }}
    with:
      Settings: ${{ needs.Get-Settings.outputs.Settings }}

  # Runs on:
  # - ✅ Open/Updated PR - Runs teardown scripts after local module tests
  # - ✅ Merged PR       - Runs teardown scripts after local module tests
  # - ✅ Abandoned PR    - Runs teardown if tests were started (cleanup)
  # - ✅ Manual run      - Runs teardown scripts after local module tests
  AfterAll-ModuleLocal:
    if: fromJson(needs.Get-Settings.outputs.Settings).Run.AfterAllModuleLocal && needs.Test-ModuleLocal.result != 'skipped' && always()
    uses: ./.github/workflows/AfterAll-ModuleLocal.yml
    secrets:
      TEST_APP_ENT_CLIENT_ID: ${{ secrets.TEST_APP_ENT_CLIENT_ID }}
      TEST_APP_ENT_PRIVATE_KEY: ${{ secrets.TEST_APP_ENT_PRIVATE_KEY }}
      TEST_APP_ORG_CLIENT_ID: ${{ secrets.TEST_APP_ORG_CLIENT_ID }}
      TEST_APP_ORG_PRIVATE_KEY: ${{ secrets.TEST_APP_ORG_PRIVATE_KEY }}
      TEST_USER_ORG_FG_PAT: ${{ secrets.TEST_USER_ORG_FG_PAT }}
      TEST_USER_USER_FG_PAT: ${{ secrets.TEST_USER_USER_FG_PAT }}
      TEST_USER_PAT: ${{ secrets.TEST_USER_PAT }}
    needs:
      - Get-Settings
      - Test-ModuleLocal
    with:
      Settings: ${{ needs.Get-Settings.outputs.Settings }}

  # Runs on:
  # - ✅ Open/Updated PR - Collects and reports test results
  # - ✅ Merged PR       - Collects and reports test results before publishing
  # - ❌ Abandoned PR    - Skips collecting results for abandoned changes
  # - ✅ Manual run      - Collects and reports test results when manually triggered
  Get-TestResults:
    if: fromJson(needs.Get-Settings.outputs.Settings).Run.GetTestResults && needs.Get-Settings.result == 'success' && always() && !cancelled()
    needs:
      - Get-Settings
      - Test-SourceCode
      - Lint-SourceCode
      - Test-Module
      - Test-ModuleLocal
    uses: ./.github/workflows/Get-TestResults.yml
    with:
      Settings: ${{ needs.Get-Settings.outputs.Settings }}

  # Runs on:
  # - ✅ Open/Updated PR - Calculates and reports code coverage
  # - ✅ Merged PR       - Calculates and reports code coverage before publishing
  # - ❌ Abandoned PR    - Skips coverage for abandoned changes
  # - ✅ Manual run      - Calculates and reports code coverage when manually triggered
  Get-CodeCoverage:
    if: fromJson(needs.Get-Settings.outputs.Settings).Run.GetCodeCoverage && needs.Get-Settings.result == 'success' && always() && !cancelled()
    needs:
      - Get-Settings
      - Test-Module
      - Test-ModuleLocal
    uses: ./.github/workflows/Get-CodeCoverage.yml
    with:
      Settings: ${{ needs.Get-Settings.outputs.Settings }}

  # Runs on:
  # - ✅ Open/Updated PR - Publishes prerelease when all tests/coverage/build succeed
  # - ✅ Merged PR       - Publishes release when all tests/coverage/build succeed
  # - ✅ Abandoned PR    - Publishes cleanup/retraction version
  # - ✅ Manual run      - Publishes when all tests/coverage/build succeed
  Publish-Module:
    if: fromJson(needs.Get-Settings.outputs.Settings).Run.PublishModule && needs.Get-Settings.result == 'success' && !cancelled() && (needs.Get-TestResults.result == 'success' || needs.Get-TestResults.result == 'skipped') && (needs.Get-CodeCoverage.result == 'success' || needs.Get-CodeCoverage.result == 'skipped') && (needs.Build-Site.result == 'success' || needs.Build-Site.result == 'skipped')
    uses: ./.github/workflows/Publish-Module.yml
    secrets:
      APIKey: ${{ secrets.APIKey }}
    needs:
      - Get-Settings
      - Get-TestResults
      - Get-CodeCoverage
      - Build-Site
    with:
      Settings: ${{ needs.Get-Settings.outputs.Settings }}

  # Runs on:
  # - ✅ Open/Updated PR - Builds documentation for review
  # - ✅ Merged PR       - Builds documentation for publishing
  # - ❌ Abandoned PR    - Skips building docs for abandoned changes
  # - ✅ Manual run      - Builds documentation when manually triggered
  Build-Docs:
    if: fromJson(needs.Get-Settings.outputs.Settings).Run.BuildDocs
    needs:
      - Get-Settings
      - Build-Module
    uses: ./.github/workflows/Build-Docs.yml
    with:
      Settings: ${{ needs.Get-Settings.outputs.Settings }}

  # Runs on:
  # - ✅ Open/Updated PR - Builds site for preview
  # - ✅ Merged PR       - Builds site for publishing
  # - ❌ Abandoned PR    - Skips building site for abandoned changes
  # - ✅ Manual run      - Builds site when manually triggered
  Build-Site:
    if: fromJson(needs.Get-Settings.outputs.Settings).Run.BuildSite
    needs:
      - Get-Settings
      - Build-Docs
    uses: ./.github/workflows/Build-Site.yml
    with:
      Settings: ${{ needs.Get-Settings.outputs.Settings }}

  # Runs on:
  # - ❌ Open/Updated PR - Site not published for PRs in progress
  # - ✅ Merged PR       - Deploys site to GitHub Pages after successful merge
  # - ❌ Abandoned PR    - Site not published for abandoned changes
  # - ❌ Manual run      - Only publishes on merged PRs, not manual runs
  Publish-Site:
    if: fromJson(needs.Get-Settings.outputs.Settings).Run.PublishSite && needs.Get-TestResults.result == 'success' && needs.Get-CodeCoverage.result == 'success' && needs.Build-Site.result == 'success' && !cancelled()
    uses: ./.github/workflows/Publish-Site.yml
    needs:
      - Get-Settings
      - Get-TestResults
      - Get-CodeCoverage
      - Build-Site
    with:
      Settings: ${{ needs.Get-Settings.outputs.Settings }}