✨ use codeowners anywhere in your monorepo 🛠️
Explore the docs »
Report Bug
·
Request Feature
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.
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
Every command accepts several options through command line or custom configuration see configuration for more
codeowners-generator generate
codeowners-generator generate --use-maintainers
codeowners-generator generate --includes '**/CODEOWNERS'
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.
You can configure codeowners-generator
from several places:
-
includes (
--includes
): The glob used to find CODEOWNERS files in the repodefault: ['**/CODEOWNERS', '!CODEOWNERS', '!.github/CODEOWNERS', '!docs/CODEOWNERS', '!node_modules']
-
output (
--output
): The output path and name of the filedefault: CODEOWNERS
-
useMaintainers (
--use-maintainers
): It will usemaintainers
field from package.json to generate codeowners, by default it will use**/package.json
-
useRootMaintainers (
--use-root-maintainers
): It will usemaintainers
field from the package.json in the root to generate default codeowners. Works only in conjunction withuseMaintainers
.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
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
orcodeowners-generator.cjs
file inside a .config subdirectory - a
codeowners-generator.config.js
orcodeowners-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.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature
) - Commit your Changes (
git commit -m 'Add some AmazingFeature'
) - Push to the Branch (
git push origin feature/AmazingFeature
) - Open a Pull Request
Distributed under the MIT License. See LICENSE
for more information.