codeowners-generator

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.

$3

- ora
- commander
- cosmiconfig

$3

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

``sh
npm -g install codeowners-generator
`

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

`sh
codeowners-generator --help
`

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

`sh
npm install --only=dev codeowners-generator
`

Usage

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

$3

`sh
codeowners-generator generate
`

$3

`sh
codeowners-generator generate --use-maintainers
`

$3

`sh
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.

`yml
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:

`yml
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:

$3

- 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.

- hidden-directories (--hidden-directories): Also include searching in hidden (dot) directories.

For more details you can invoke:

`sh
codeowners-generator --help
`

$3

You can also define custom configuration in your package:

`json
{
"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.

`bash
(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.