https://github.com/gagoar/codeowners-generator

CODEOWNERS solution for mono repos
https://github.com/gagoar/codeowners-generator

cli codeowners codeowners-files codeowners-generator monorepo

Last synced: 1 day ago
JSON representation

CODEOWNERS solution for mono repos

• Host: GitHub
• URL: https://github.com/gagoar/codeowners-generator
• Owner: gagoar
• License: mit
• Created: 2020-07-28T01:33:31.000Z (over 4 years ago)
• Default Branch: master
• Last Pushed: 2024-04-09T08:07:32.000Z (7 months ago)
• Last Synced: 2024-04-09T09:28:04.899Z (7 months ago)
• Topics: cli, codeowners, codeowners-files, codeowners-generator, monorepo
• Language: TypeScript
• Homepage: https://gagoar.github.io/codeowners-generator/
• Size: 1.26 MB
• Stars: 48
• Watchers: 4
• Forks: 8
• Open Issues: 20
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-monorepo - CODEOWNERS 生成器

README

        



    

      

    

    

      

    

    

      

    

    

      

    





  
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](#about-the-project)

- [Built With](#built-with)

- [Installation](#installation)

- [Configuration](#configuration)

- [Usage](#usage)

- [Action](#action)

- [Contributing](#contributing)

- [License](#license)

## About The Project

[CODEOWNERS](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners) 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](https://docs.npmjs.com/files/package.json#people-fields-author-contributors).

### Built With

- [ora](https://github.com/sindresorhus/ora)

- [commander](https://github.com/tj/commander.js/)

- [cosmiconfig](https://github.com/davidtheclark/cosmiconfig)

### Installation

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](#configuration)

### Generate CODEOWNERS file

```sh

  codeowners-generator generate

```

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

```sh

codeowners-generator generate --use-maintainers

```

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

```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 "[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).

## 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:

```sh

  codeowners-generator --help

```

### Custom Configuration

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](https://github.com/davidtheclark/cosmiconfig)

## Roadmap

See the [open issues](https://github.com/gagoar/codeowners-generator/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.