{"id":16594508,"url":"https://github.com/sverweij/virtual-code-owners","last_synced_at":"2025-03-21T13:32:07.342Z","repository":{"id":62847922,"uuid":"540597864","full_name":"sverweij/virtual-code-owners","owner":"sverweij","description":"CODEOWNERS with teams for teams that can't use GitHub teams","archived":false,"fork":false,"pushed_at":"2024-10-03T19:24:42.000Z","size":641,"stargazers_count":4,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-12T23:46:20.940Z","etag":null,"topics":["codeowners"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/virtual-code-owners","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sverweij.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-23T19:56:59.000Z","updated_at":"2024-10-03T19:22:32.000Z","dependencies_parsed_at":"2023-10-14T15:36:06.471Z","dependency_job_id":"6697e060-9b24-49b2-af21-d386811088da","html_url":"https://github.com/sverweij/virtual-code-owners","commit_stats":{"total_commits":76,"total_committers":2,"mean_commits":38.0,"dds":0.4342105263157895,"last_synced_commit":"114bf97131292d9649e7c9dc37a2514813fcf7a4"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sverweij%2Fvirtual-code-owners","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sverweij%2Fvirtual-code-owners/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sverweij%2Fvirtual-code-owners/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sverweij%2Fvirtual-code-owners/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sverweij","download_url":"https://codeload.github.com/sverweij/virtual-code-owners/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221815686,"owners_count":16885205,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codeowners"],"created_at":"2024-10-11T23:46:28.592Z","updated_at":"2024-10-28T10:13:25.466Z","avatar_url":"https://github.com/sverweij.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## What?\n\nThis generates your `CODEOWNERS` file (_patterns_ x _users_) from\n\n- a `VIRTUAL-CODEOWNERS.txt` (_patterns_ x _teams_)\n- a `virtual-teams.yml` (_teams_ x _users_)\n\n... which makes it easier to keep `CODEOWNERS` in sync on multi-team mono repos\nwhen you don't have (enough) 'real' GitHub or GitLab teams.\n\n## Usage\n\n- Rename `.github/CODEOWNERS` to `.github/VIRTUAL-CODEOWNERS.txt` and put team names in them.\n- Define teams that don't (yet) exist on GitHub level in `.github/virtual-teams.yml`\n- Run this:\n\n```\nnpx virtual-code-owners\n# Wrote '.github/CODEOWNERS'\n```\n\n- :sparkles:\n\n## Formats\n\n### VIRTUAL-CODEOWNERS.txt\n\n`VIRTUAL-CODEOWNERS.txt` sticks to the [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) format,\nbut adds the ability to include teams defined in `virtual-teams.yml`.\n\nFor example a CODEOWNERS file can look like this:\n\n```CODEOWNERS\n#! comments that start with #! won't appear in the CODEOWNERS output\n#!\n#! this is not the CODEOWNERS file - to get that one run\n#!   npx virtual-code-owners\n#!\n# catch-all to ensure there at least _is_ a code owner, even when\n# it's _everyone_\n\n* @cloud-heroes-all\n\n# admin \u0026 ci stuff =\u003e transversal\n\n.github/            @ch/transversal\n\n# generic stuff\n\napps/framework/     @ch/transversal\napps/ux-portal/     @ch/ux @ch/transversal\nlibs/components/    @ch/ux\n\n# specific functionality\n\nlibs/sales/         @ch/sales\nlibs/after-sales/   @ch/after-sales\nlibs/refund/        @ch/sales @ch/after-sales\nlibs/baarden/       @ch/mannen-met-baarden\n```\n\n... where only the @cloud-heroes-all is a 'real' team on GitHub level. The other\nones are defined in `virtual-teams.yml`.\n\n### virtual-teams.yml\n\nA valid YAML file that contains a list of teams and their members.\nUpdate it whenever you have new team members and run `npx virtual-code-owners`\nto keep CODEOWNERS current.\n\n```yaml\n# yaml-language-server: $schema=https://raw.githubusercontent.com/sverweij/virtual-code-owners/main/src/virtual-teams.schema.json\nch/after-sales:\n  - john-doe-ch\n  - pete-peterson-ch\n  - john-galt-ch\n  - daisy-duck\n  - donald-duck\nch/sales:\n  - gregory-gregson-ch\n  - jane-doe-ch\n  - abraham-ableton-ch\n  - dagny-taggert-ch\n  - karl-marx-ch\nch/ux:\n  - davy-davidson-ch\n  - john-johnson-ch\n  - joe-dalton-ch\n  - koos-koets\nch/transversal:\n  - mary-the-merry-ch\n  - luke-the-lucky-ch\n  - benjamin-franklin\n  - koos-koets\n  - abraham-lincoln\nch/mannen-met-baarden:\n  - jan@example.com\n  - pier@example.com\n  - tjorus@example.com\n  - korneel@example.com\n```\n\n### CODEOWNERS\n\nRunning `npx virtual-code-owners` will combine these into a CODEOWNERS file like this:\n\n```CODEOWNERS\n#\n# DO NOT EDIT - this file is generated and your edits will be overwritten\n#\n# To make changes:\n#\n#   - edit .github/VIRTUAL-CODEOWNERS.txt\n#   - and/ or add team members to .github/virtual-teams.yml\n#   - run 'npx virtual-code-owners' (or 'npx virtual-code-owners --emitLabeler' if you also\n#     want to generate a .github/labeler.yml)\n#\n\n# catch-all to ensure there at least _is_ a code owner, even when\n# it's _everyone_\n\n* @cloud-heroes-all\n\n# admin \u0026 ci stuff =\u003e transversal\n\n.github/            @abraham-lincoln @benjamin-franklin @koos-koets @luke-the-lucky-ch @mary-the-merry-ch\n\n# generic stuff\n\napps/framework/     @abraham-lincoln @benjamin-franklin @koos-koets @luke-the-lucky-ch @mary-the-merry-ch\napps/ux-portal/     @abraham-lincoln @benjamin-franklin @davy-davidson-ch @joe-dalton-ch @john-johnson-ch @koos-koets @luke-the-lucky-ch @mary-the-merry-ch\nlibs/components/    @davy-davidson-ch @joe-dalton-ch @john-johnson-ch @koos-koets\n\n# specific functionality\n\nlibs/sales/         @abraham-ableton-ch @dagny-taggert-ch @gregory-gregson-ch @jane-doe-ch @karl-marx-ch\nlibs/after-sales/   @daisy-duck @donald-duck @john-doe-ch @john-galt @pete-peterson-ch\nlibs/refund/        @abraham-ableton-ch @dagny-taggert-ch @daisy-duck @donald-duck @gregory-gregson-ch @jane-doe-ch @john-doe-ch @john-galt @karl-marx-ch @pete-peterson-ch\nlibs/baarden/       jan@example.com korneel@example.com pier@example.com tjorus@example.com\n```\n\n## FAQ\n\n### Any gotcha's?\n\n- It won't check whether the users or teams you entered exist.\n\n### Do I have to run this each time I edit `VIRTUAL-CODEOWNERS.txt`?\n\nYes. But please automate this for your own sake.\n\nYou can for instance set up a rule for `lint-staged` in a `.lintstagedrc.json`\nlike this:\n\n```json\n{\n  \".github/{VIRTUAL-CODEOWNERS.txt,virtual-teams.yml}\": [\n    \"virtual-code-owners\",\n    \"git add .\"\n  ]\n}\n```\n\n### Can I mix real and virtual teams in `VIRTUAL-CODEOWNERS.txt`?\n\nYes.\n\nIt might be you already have a team or two defined, but just want to use\n_additional_ teams. In that case just don't specify the already-defined teams\nin `virtual-teams.yml` and _virtual-code-owners_ will leave them alone.\n\n### Can I still use usernames in `VIRTUAL-CODEOWNERS.txt`?\n\nYes.\n\nJust make sure there's no name clashes between the username and a (virtual)\nteam name and _virtual-code-owners_ will leave the real name alone.\n\n### Can I automatically label PR's for virtual teams?\n\nYep.\n\nUse [actions/labeler](https://github.com/actions/labeler) and tickle\n`virtual-code-owners` to generate the labeler config file:\n\n```sh\nnpx virtual-code-owners --emitLabeler\n# Wrote .github/CODEOWNERS AND .github/labeler.yml\n```\n\nIf you have an alternate file location for the `labeler.yml` you can specify that\nwith virtual-code-owner's `--labelerLocation` parameter.\n\n\u003e [!NOTE]\n\u003e actions/labeler changed the labeler.yml format from v4 to v5.\n\u003e\n\u003e - virtual-code-owners \u003c 8.0.0 generates labeler.yml v4 format,\n\u003e - virtual-code-owners \u003e= 8.0.0 generates labeler.yml v5 format.\n\u003e\n\u003e see [actions/labeler#v5](https://github.com/actions/labeler/blob/8558fd74291d67161a8a78ce36a881fa63b766a9/README.md)\n\u003e for details on the v5 format.\n\n### What validations does virtual-code-owners perform?\n\nvirtual-code-owners checks for basic CODEOWNERS format errors and invalid\nuser/team names but doesn't verify their existence in the project.\n\n- valid user/team names start with an `@` or are an e-mail address\n- valid rules have a file pattern and at least one user/team name\n  (unless they're in a _section_ that has default owners `[sales related] @ch/sales`\n  in which case the rule inherits the default owners of that section)\n- valid sections headings comply with the syntax described over at [GitLab](https://docs.gitlab.com/ee/user/project/codeowners/reference.html#sections)\n  \u003e different from GitLab's syntax the line `[bla @group` is not interpreted\n  \u003e as a rule, but as an erroneous section heading. This behaviour might change\n  \u003e to be the same as GitLab's in future releases without a major version bump.\n\n### Does virtual-code-owners support GitLab style sections?\n\nYes.\n\n### I want to specify different locations for the files (e.g. because I'm using GitLab)\n\nHere you go:\n\n```\nnpx virtual-code-owners \\\n  --virtualCodeOwners .gitlab/VIRTUAL-CODEOWNERS.txt \\\n  --virtualTeams      .gitlab/virtual-teams.yml \\\n  --codeOwners        .gitlab/CODEOWNERS\n```\n\n### Can I just validate VIRTUAL-CODEOWNERS.txt \u0026 virtual-teams.yml without generating output?\n\nSure thing. Use `--dryRun`:\n\n```\nnpx virtual-code-owners --dryRun\n```\n\n### Why the `.txt` extension?\n\nIt keeps editors and IDE's from messing up your formatting.\n\nVarious editors assume an ALL_CAPS file name with `#` characters on various lines\nto be markdown, and will auto format them as such. Usually such autoformatting is\nnot present on text files.\n\nOften these editors know about CODEOWNERS, so they won't confuse _those_ with\nmarkdown.\n\n### Why does this exist at all? Why not just use GitHub teams?\n\nIf you can you should _totally_ use GitHub teams!\n\nOrganizations sometimes have large mono repositories with many code owners.\nThey or their bureaucracy haven't landed on actually using GitHub teams to\ndemarcate that. Or you're working on a cross-functional team that doesn't follow\nthe organization chart (and hence the GitHub teams). Teams in those organizations\nwho want to have clear code ownership can either:\n\n- Wrestle the bureaucracy.  \n  Recommended! It will often require patience though, and in the mean time\n  you might want to have some clarity on code ownership.\n- Maintain a CODEOWNERS file with code assigned to large lists of individuals.  \n  That's a lotta work, even for smaller projects\n\nThis is where `virtual-code-owners` comes in.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsverweij%2Fvirtual-code-owners","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsverweij%2Fvirtual-code-owners","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsverweij%2Fvirtual-code-owners/lists"}