gh-action.md

← back to docs

GitHub Action for CODEOWNERS Validator

Ensures the correctness of your CODEOWNERS file.

The Codeowners Validator is available as a GitHub Action.

Usage

Create a workflow (eg: .github/workflows/sanity.yml see Creating a Workflow file)

name: "Codeowners Validator"

on:
  schedule:
    # Runs at 08:00 UTC every day
    - cron:  '0 8 * * *'

jobs:
  sanity:
    runs-on: ubuntu-latest
    steps:
      # Checks-out your repository, which is validated in the next step
      - uses: actions/checkout@v2
      - name: GitHub CODEOWNERS Validator
        uses: mszostok/codeowners-validator@v0.7.4
        # input parameters
        with:
          # ==== GitHub Auth ====

          ## ==== PAT ====
          # GitHub access token is required only if the `owners` check is enabled
          github_access_token: "${{ secrets.OWNERS_VALIDATOR_GITHUB_SECRET }}"

          ## ==== App ====
          # GitHub App ID for authentication. This replaces the github_access_token.
          github_app_id: ${{ secrets.APP_ID }}

          # GitHub App Installation ID. Required when github_app_id is set.
          github_app_installation_id: ${{ secrets.APP_INSTALLATION_ID }}

          # GitHub App private key in PEM format. Required when github_app_id is set.
          github_app_private_key: ${{ secrets.APP_PRIVATE_KEY }}

          # ==== GitHub Auth ====

          # "The list of checks that will be executed. By default, all checks are executed. Possible values: files,owners,duppatterns,syntax"
          checks: "files,owners,duppatterns,syntax"

          # "The comma-separated list of experimental checks that should be executed. By default, all experimental checks are turned off. Possible values: notowned,avoid-shadowing"
          experimental_checks: "notowned,avoid-shadowing"

          # The GitHub base URL for API requests. Defaults to the public GitHub API, but can be set to a domain endpoint to use with GitHub Enterprise.
          github_base_url: "https://api.github.com/"

          # The GitHub upload URL for uploading files. It is taken into account only when the GITHUB_BASE_URL is also set. If only the GITHUB_BASE_URL is provided then this parameter defaults to the GITHUB_BASE_URL value.
          github_upload_url: "https://uploads.github.com/"

          # The repository path in which CODEOWNERS file should be validated."
          repository_path: "."

          # Defines the level on which the application should treat check issues as failures. Defaults to warning, which treats both errors and warnings as failures, and exits with error code 3. Possible values are error and warning. Default: warning"
          check_failure_level: "warning"

          # The comma-separated list of patterns that should be ignored by not-owned-checker. For example, you can specify * and as a result, the * pattern from the CODEOWNERS file will be ignored and files owned by this pattern will be reported as unowned unless a later specific pattern will match that path. It's useful because often we have default owners entry at the begging of the CODOEWNERS file, e.g. * @global-owner1 @global-owner2"
          not_owned_checker_skip_patterns: ""

          # The owner and repository name. For example, gh-codeowners/codeowners-samples. Used to check if GitHub team is in the given organization and has permission to the given repository."
          owner_checker_repository: "${{ github.repository }}"

          # The comma-separated list of owners that should not be validated. Example: @owner1,@owner2,@org/team1,example@email.com."
          owner_checker_ignored_owners: "@ghost"

          # Specifies whether CODEOWNERS may have unowned files. For example, `/infra/oncall-rotator/oncall-config.yml` doesn't have owner and this is not reported.
          owner_checker_allow_unowned_patterns: "true"

          # Specifies whether only teams are allowed as owners of files.
          owner_checker_owners_must_be_teams: "false"

          # Only check listed subdirectories for CODEOWNERS ownership that don't have owners.
          not_owned_checker_subdirectories: ""

The best is to run this as a cron job and not only if you applying changes to CODEOWNERS file itself, e.g. the CODEOWNERS file can be invalidate when you removing someone from the organization.

Note

To execute owners check you need to create a GitHub token and store it as a secret in your repository, see "Creating and storing encrypted secrets.". Token requires only read-only scope for your repository.

Configuration

For the GitHub Action, use the configuration described in the main README under the Configuration section but specify it as the Action input parameters instead of environment variables. See the Usage section for the full syntax.

If you want to use environment variables anyway, you must add the INPUT_ prefix to each environment variable. For example, OWNER_CHECKER_IGNORED_OWNERS becomes INPUT_OWNER_CHECKER_IGNORED_OWNERS.