Codeowners-generator NPM

About The Project

CODEOWNERS are automatically requested for review when someone opens a pull request that modifies code that they own. This is a great feature, but when working on monorepos ownership is shared between teams and it becomes difficult to maintain.

codeowners-generator allows you to position CODEOWNERS files anywhere in your project tree and it will take care of compiling all the files into a single generated file, that Github can understand. It also can read the maintainers fields (contributors, author and alternatively maintainers) in package.json (--use-maintainers option in the cli ) making easy to keep CODEOWNERS and package.json in sync. Make sure the author/contributors syntax matches with package.json expected syntax from the documentation.

Built With

Installation

If you wish to use codeowners-generator as a standalone utility:

npm -g install codeowners-generator

This will make the codeowners-generator command available in your terminal.

codeowners-generator --help

If instead you would like to add it to a package:

npm install --only=dev codeowners-generator

Usage

Every command accepts several options through command line or custom configuration see configuration for more

Generate CODEOWNERS file

  codeowners-generator generate

Generate CODEOWNERS file (using `maintainers` field from `package.json`)

codeowners-generator generate --use-maintainers

Specify CODEOWNERS (in case the CODEOWNERS files are named differently)

  codeowners-generator generate --includes '**/CODEOWNERS'

Action

Now you can use codeowners-generator to validate if the CODEOWNERS file has been updated during a Pull Request.

name: Lint CODEOWNERS

on:
  pull_request:

jobs:
  codeowners:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2 # to checkout the code of the repo you want to check the CODEOWNERS from.
      - name: check codeowners
        uses: gagoar/codeowners-generator@master
        with:
          use-maintainers: true
          check: true

You can also use it to update the Pull Request. For that, you will need a GitHub App or Personal Token with the necessary permissions (code content). The code for that will look roughly like this:

name: update CODEOWNERS

on:
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: gagoar/codeowners-generator@master
        with:
          use-maintainers: true
      - run: |
          STATUS=$(git diff --quiet && echo clean || echo modified)
          echo "status=$(echo $STATUS)" >> $GITHUB_OUTPUT
        id: gitStatus
      - run: |
          echo ${{ steps.gitStatus.outputs.status }}
          echo ${{ contains(steps.gitStatus.outputs.status, 'modified') }}
      - name: Commit CODEOWNERS
        if: contains(steps.gitStatus.outputs.status, 'modified')
        run: |
          set -x
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add CODEOWNERS
          git commit -m "update CODEOWNERS"
      - id: auth
        if: contains(steps.gitStatus.outputs.status, 'modified')
        uses: jnwng/github-app-installation-token-action@v2
        with:
          appId: ${{ secrets.YOUR_APP_ID }}
          installationId: ${{ secrets.YOUR_APP_INSTALLATION_ID }}
          privateKey: ${{ secrets.YOUR_APP_PRIVATE_KEY }}
      - name: Push changes
        if: contains(steps.gitStatus.outputs.status, 'modified')
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ steps.auth.outputs.token }}
          branch: ${{github.head_ref}}

Remember that you can always create a configuration file in your project that will be picked up by the tool running on the action. For examples in how to configure take a look at the configuration section below.

Configuration

You can configure codeowners-generator from several places:

CLI options

includes (--includes): The glob used to find CODEOWNERS files in the repo default: ['**/CODEOWNERS', '!CODEOWNERS', '!.github/CODEOWNERS', '!docs/CODEOWNERS', '!node_modules']
output (--output): The output path and name of the file default: CODEOWNERS
useMaintainers (--use-maintainers): It will use maintainers field from package.json to generate codeowners, by default it will use **/package.json
useRootMaintainers (--use-root-maintainers): It will use maintainers field from the package.json in the root to generate default codeowners. Works only in conjunction with useMaintainers. default: false
groupSourceComments (--group-source-comments): Instead of generating one comment per rule, enabling this flag will group them, reducing comments to one per source file. Useful if your codeowners file gets too noisy.
preserveBlockPosition (--preserve-block-position): It will keep the generated block in the same position it was found in the CODEOWNERS file (if present). Useful for when you make manual additions.
customRegenerationCommand (--custom-regeneration-command): Specify a custom regeneration command to be printed in the generated CODEOWNERS file, it should be mapped to run codeowners-generator (e.g. "npm run codeowners").
check (--check): It will fail if the CODEOWNERS generated doesn't match the current (or missing) CODEOWNERS . Useful for validating that the CODEOWNERS file is not out of date during CI.

For more details you can invoke:

  codeowners-generator --help

Custom Configuration

You can also define custom configuration in your package:

{
  "name": "my-package",
  "codeowners-generator": {
    "includes": ["**/CODEOWNERS"],
    "output": ".github/CODEOWNERS",
    "useMaintainers": true,
    "useRootMaintainers": true,
    "groupSourceComments": true,
    "customRegenerationCommand": "npm run codeowners"
  },
  "scripts": {
    "codeowners": " codeowners-generator generate"
  },
  "devDependencies": {
    "codeowners-generator": "^2.0.0"
  }
}

When the command is invoked it will look for the codeowners-generator configuration block.

(my-package)$ npm run codeowners

If you create any files matching the following patterns, codeowners-generator will pick them up:

a codowners-generator property in package.json
a .codowners-generatorrc file in JSON or YAML format
a .codowners-generator.json, .codowners-generator.yaml, .codowners-generator.yml, .codowners-generator.js, or .codowners-generator.cjs file
a codowners-generatorrc, codowners-generator.json, codowners-generatorrc.yaml, codowners-generatorrc.yml, codowners-generator.js or codowners-generator.cjs file inside a .config subdirectory
a codowners-generator.config.js or codowners-generator.config.cjs CommonJS module exporting an object

For more insight into the custom configuration and where it can be defined check cosmiconfig

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what makes the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated greatly appreciated.