Skip to content
You're viewing an older version of this GitHub Action. Do you want to see the latest version instead?
shield

GitHub Action

GitHub CODEOWNERS Validator

v0.4.0

GitHub CODEOWNERS Validator

shield

GitHub CODEOWNERS Validator

GitHub action to ensure the correctness of your CODEOWNERS file

Installation

Copy and paste the following snippet into your .yml file.

              

- name: GitHub CODEOWNERS Validator

uses: mszostok/codeowners-validator@v0.4.0

Learn more about this action in mszostok/codeowners-validator

Choose a version

GitHub CODEOWNERS Validator

Ensures the correctness of your CODEOWNERS file.

Software License Go Report Card Travis


The Codeowners Validator project validates the GitHub CODEOWNERS file using those checks. It supports public and private GitHub repositories and also GitHub Enterprise installations.

usage

Usage

Docker

export GH_TOKEN=<your_token>
docker run --rm -v $(pwd):/repo -w /repo \
  -e REPOSITORY_PATH="." \
  -e GITHUB_ACCESS_TOKEN="$GH_TOKEN" \
  -e EXPERIMENTAL_CHECKS="notowned" \
  -e OWNER_CHECKER_REPOSITORY="org-name/rep-name" \
  mszostok/codeowners-validator:v0.4.0

Command line

export GH_TOKEN=<your_token>
env REPOSITORY_PATH="." \
    GITHUB_ACCESS_TOKEN="$GH_TOKEN" \
    EXPERIMENTAL_CHECKS="notowned" \
    OWNER_CHECKER_REPOSITORY="org-name/rep-name" \
  codeowners-validator

GitHub Action

- uses: mszostok/codeowners-validator@v0.4.0
  with:
    checks: "files,owners,duppatterns"
    experimental_checks: "notowned"
    # GitHub access token is required only if the `owners` check is enabled
    github_access_token: "${{ secrets.OWNERS_VALIDATOR_GITHUB_SECRET }}"

Check this document for more information about GitHub Action.


Check the Configuration section for more info on how to enable and configure given checks.

Installation

It's highly recommended to install a fixed version of codeowners-validator. Releases are available on the releases page.

From Release

Here is the recommended way to install codeowners-validator:

# binary installed into ./bin/
curl -sfL https://raw.githubusercontent.com/mszostok/codeowners-validator/master/install.sh| sh -s v0.4.0

# binary installed into $(go env GOPATH)/bin/codeowners-validator
curl -sfL https://raw.githubusercontent.com/mszostok/codeowners-validator/master/install.sh| sh -s -- -b $(go env GOPATH)/bin v0.4.0

# In alpine linux (as it does not come with curl by default)
wget -O - -q https://raw.githubusercontent.com/mszostok/codeowners-validator/master/install.sh| sh -s v0.4.0

# Print version. Add `--short` to print just the version number.
codeowners-validator -v

You can also download latest version from release page manually.

From Sources

You can install codeowners-validator with env GO111MODULE=on go get -u github.com/mszostok/codeowners-validator.

NOTE: please use the latest Go to do this, ideally Go 1.12 or greater.

This will put codeowners-validator in $(go env GOPATH)/bin

Configuration

Use the following environment variables to configure the application:

Name Default Description
REPOSITORY_PATH * The repository path to your repository on your local machine.
GITHUB_ACCESS_TOKEN The GitHub access token. Instruction for creating a token can be found here. If not provided then validating owners functionality could not work properly, e.g. you can reach the API calls quota or if you are setting GitHub Enterprise base URL then an unauthorized error can occur.
GITHUB_BASE_URL https://api.github.com/ 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_UPLOAD_URL https://uploads.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.
CHECKS - The list of checks that will be executed. By default, all checks are executed. Possible values: files,owners,duppatterns
EXPERIMENTAL_CHECKS - The comma-separated list of experimental checks that should be executed. By default, all experimental checks are turned off. Possible values: notowned.
CHECK_FAILURE_LEVEL warning 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.
OWNER_CHECKER_REPOSITORY * The owner and repository name separated by slash. For example, gh-codeowners/codeowners-samples. Used to check if GitHub owner is in the given organization.
NOT_OWNED_CHECKER_SKIP_PATTERNS - 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

* - Required

Checks

The following checks are enabled by default:

Name Description
duppatterns [Duplicated Pattern Checker]

Reports if CODEOWNERS file contain duplicated lines with the same file pattern.
files [File Exist Checker]

Reports if CODEOWNERS file contain lines with the file pattern that do not exist in a given repository.
owners [Valid Owner Checker]

Reports if CODEOWNERS file contain invalid owners definition. Allowed owner syntax: @username, @org/team-name or user@example.com
source: https://help.github.com/articles/about-code-owners/#codeowners-syntax.

Checks:
1. Check if the owner's definition is valid (is either a GitHub user name, an organization team name or an email address).

2. Check if a GitHub owner has a GitHub account

3. Check if a GitHub owner is in a given organization

4. Check if an organization team exists

The experimental checks are disabled by default:

Name Description
notowned [Not Owned File Checker]

Reports if a given repository contain files that do not have specified owners in CODEOWNERS file.

To enable experimental check set EXPERIMENTAL_CHECKS=notowned environment variable.

Check the Configuration section for more info on how to enable and configure given checks.

Exit status codes

Application exits with different status codes which allow you to easily distinguish between error categories.

Code Description
1 The application startup failed due to the wrong configuration or internal error.
2 The application was closed because the OS sends a termination signal (SIGINT or SIGTERM).
3 The CODEOWNERS validation failed - executed checks found some issues.

Roadmap

The codeowners-validator roadmap uses Github milestones to track the progress of the project.

They are sorted with priority. First are most important.