CODEOWNERS generator for mono-repos
npm install codeowners-generator
✨ use codeowners anywhere in your monorepo 🛠️
Explore the docs »
Report Bug
·
Request Feature
- About the Project
- Built With
- Installation
- Configuration
- Usage
- Action
- Contributing
- License
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.
- ora
- commander
- cosmiconfig
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
Every command accepts several options through command line or custom configuration see configuration for more
`sh`
codeowners-generator generate
`sh`
codeowners-generator generate --use-maintainers
`sh`
codeowners-generator generate --includes '**/CODEOWNERS'
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.
You can configure codeowners-generator from several places:
- 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
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.codeowners-generatorrc
- a file in JSON or YAML format.codeowners-generator.json
- a , .codeowners-generator.yaml, .codeowners-generator.yml, .codeowners-generator.js, or .codeowners-generator.cjs filecodeowners-generatorrc
- a , codeowners-generator.json, codeowners-generatorrc.yaml, codeowners-generatorrc.yml, codeowners-generator.js or codeowners-generator.cjs file inside a .config subdirectorycodeowners-generator.config.js
- a 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
See the open issues for a list of proposed features (and known issues).
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)git commit -m 'Add some AmazingFeature'
3. Commit your Changes ()git push origin feature/AmazingFeature
4. Push to the Branch ()
5. Open a Pull Request
Distributed under the MIT License. See LICENSE` for more information.