codeowners-validation.yml

name: "CodeOwners Validation"

on:
  pull_request:

jobs:
  # This job is necessary because the org-wide rulesets don't support event-based path filtering.
  # (https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#running-your-pull_request-workflow-based-on-files-changed-in-a-pull-request)
  # We include this job to filter the paths manually.
  filter-changes:
    name: Filter changes
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
    outputs:
      codeowners: ${{ steps.filter.outputs.codeowners }}
    steps:
      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
        id: filter
        with:
          filters: |
            codeowners:
              - ".github/CODEOWNERS"
              - "CODEOWNERS"

  validate-codeowners:
    name: "Validate"
    runs-on: ubuntu-latest
    needs: filter-changes
    permissions:
      contents: read
      id-token: write
    if: ${{ needs.filter-changes.outputs.codeowners == 'true' }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1
          persist-credentials: false

      - name: Setup GitHub Token
        id: gh-token
        uses: smartcontractkit/.github/actions/setup-github-token@main
        with:
          aws-role-arn: ${{ secrets.GATI_CODEOWNERS_IAM_ARN }}
          aws-lambda-url: ${{ secrets.GATI_CODEOWNERS_LAMBDA_URL }}
          aws-region: "us-west-2"

      - name: GitHub CODEOWNERS Validator
        uses: patrickhuie19/codeowners-validator@176f0bfd300c754c6cc8d4a9e9863323e6752b90 # v0.1.8
        with:
          github_access_token: ${{ steps.gh-token.outputs.access-token }}
          repository_path: ${{ github.workspace }}
          owner_checker_repository: ${{ github.repository }}

          # List of validation checks to execute (comma-separated)
          # Available: files, owners, duppatterns, syntax, patterns
          checks: "files,owners,duppatterns,syntax,patterns"

          # List of experimental validation checks (comma-separated)
          # Available: notowned, avoid-shadowing
          # Note: 'notowned' is disabled pending arm64 support
          experimental_checks: "avoid-shadowing"

          # Failure level for check issues
          # Available: error, warning (default: warning)
          check_failure_level: "error"

          # Patterns to ignore in not-owned-checker (comma-separated)
          # Example: Use "*" to ignore global ownership patterns
          not_owned_checker_skip_patterns: ""

          # Owners to exclude from validation (comma-separated)
          # Format: @owner, @org/team, email@example.com
          owner_checker_ignored_owners: "@ghost"

          # Whether to allow files without explicit owners
          owner_checker_allow_unowned_patterns: "false"

          # Enforce team-only ownership
          owner_checker_owners_must_be_teams: "true"

          # Specific subdirectories to check for ownership
          not_owned_checker_subdirectories: ""

          # Patterns to exclude from validation (comma-separated)
          pattern_checker_ignored_patterns: ""

      - name: Print Summary
        if: always()
        run: |
          cat <<'EOF' >> $GITHUB_STEP_SUMMARY
          ## CODEOWNERS Validation Guidelines

          <details>
          <summary>🔍 Pattern Order Issues</summary>

          * Ensure patterns are ordered from least specific to most specific.
          * More general paths must come BEFORE more specific ones.
          * Example:
            ```
            # ✅ Correct order (general to specific)
            * @org/core-team              # Most general
            /docs/* @org/docs-team        # More specific
            /docs/api/* @org/api-team     # Most specific

            # ❌ Incorrect order (causes shadowing)
            /docs/api/* @org/api-team     # Specific pattern shadows general ones
            /docs/* @org/docs-team        # Never matches due to shadowing
            * @org/core-team              # Never matches due to shadowing
            ```
          </details>

          <details>
          <summary>🔍 Duplicate Patterns</summary>

          * Verify that each pattern is defined only once.
          * Remove duplicate definitions to prevent inconsistent ownership.
          * Use your editor's search (e.g. git grep) to locate duplicates.
          </details>

          <details>
          <summary>🔍 Non-Existent Paths</summary>

          * Review patterns that do not match any files in the repository.
          * Check paths for typos or changes in repository structure.
          * Remove patterns referencing deleted files or directories.
          </details>

          <details>
          <summary>🔍 Discrete File Issues</summary>

          * Warnings like "Discrete file" indicate patterns match a single file.
          * Discrete file patterns are hard to maintain, and also indicate a lack of shared knowledge.
          * Verify if the specific file path is intended.
          * If not, update the pattern to target the correct file(s).
          </details>

          <details>
          <summary>🔍 Deeply Nested Pattern Issues</summary>

          * "Deeply nested pattern" warnings suggest patterns may be too specific.
          * This error occurs when the path contains more than 3 levels of nesting.
          * Consider simplifying patterns to improve maintainability.
          * Check if excessive nesting is necessary or if a broader pattern could suffice.
          </details>

          <details>
          <summary>🔍 Owner Issues</summary>

          * Every pattern must have at least one owner.
          * Replace individual users with team mentions where required.
          * Remove multiple owner declarations; consolidate into the relevant team.
          * Ensure only team owners are used if that rule is enforced.
          </details>

          <details>
          <summary>🔍 Best Practices</summary>

          1. Use team mentions instead of individual accounts.
          2. Keep patterns simple and maintainable.
          3. Regularly update and clean up ownership patterns.
          4. Use wildcards sparingly and only when necessary.
          5. Document any special cases with inline comments.
          </details>

          <details>
          <summary>Example of a Well-Structured CODEOWNERS</summary>

          ```
          # Core application
          * @org/core-team

          # Documentation
          docs/* @org/docs-team

          # Specific features
          src/features/auth/* @org/security-team
          src/features/api/* @org/api-team
          ```
          </details>
          EOF