codeowners-generator

this project is sponsored by:

✨ use codeowners anywhere in your monorepo 🛠️
Explore the docs »
Report Bug · Request Feature

Table of Contents

• About the Project
• Built With
• Installation
• Configuration
• Usage
• Action
• Contributing
• License

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

• ora
• commander
• cosmiconfig

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 "[email protected]"
          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 codeowners-generator property in package.json
• a .codeowners-generatorrc file in JSON or YAML format
• a .codeowners-generator.json, .codeowners-generator.yaml, .codeowners-generator.yml, .codeowners-generator.js, or .codeowners-generator.cjs file
• a codeowners-generatorrc, codeowners-generator.json, codeowners-generatorrc.yaml, codeowners-generatorrc.yml, codeowners-generator.js or codeowners-generator.cjs file inside a .config subdirectory
• a codeowners-generator.config.js or codeowners-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.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.