split-by-codeowners

Split a set of local changes into CODEOWNERS buckets and (optionally) create one PR per bucket.

Works in two modes sharing the same core logic:

- GitHub Action: run in CI after your codemod step; generates patches + can create/update PRs (no third-party PR actions).
- CLI (npx): run locally to bucketize current working tree changes; can create/update PRs using gh for best dev UX.

Why

If a codemod touches files owned by different teams, you often want:

- smaller PRs
- clearer ownership/review routing
- independent merge/rollback per owner group

This tool groups changed files by their effective CODEOWNERS owner set (last-match-wins semantics).

Quickstart (GitHub Action)

``yaml
permissions:
contents: write
pull-requests: write

steps:
- uses: actions/checkout@v4
- name: Run codemods
run: ./run-codemods.sh

- name: Split into CODEOWNERS PRs
uses: anatoliisf/split-by-codeowners@v1
with:
github_token: ${{ github.token }}
`

Quickstart (CLI)

Bucketize + write patches:

`bash
npx split-by-codeowners
`

Create/update PRs locally (recommended: gh auth):

`bash
gh auth login -h github.com
npx split-by-codeowners --create-prs --base-branch main
`

GitHub Action

$3

| Name | Required | Default | Description |
| -------------------- | -------- | ------------------------------------- | ----------------------------------------------------------------------------- |
| repo_path | no | . | Repo root path relative to GITHUB_WORKSPACE |
| codeowners_path | no | CODEOWNERS | Path to CODEOWNERS file |
| base_ref | no | "" | Base ref for changed-files discovery (currently workspace-focused; see notes) |
| include_unowned | no | "true" | Include files with no owners in a special bucket |
| unowned_bucket_key | no | __UNOWNED__ | Bucket key for unowned files |
| max_buckets | no | "30" | Fail if buckets exceed this number |
| exclude_patterns | no | "" | Newline-separated glob patterns to exclude (minimatch) |
| patch_dir | no | bucket-patches | Directory to write per-bucket patch files |
| bucket_prefix | no | bucket | Patch file prefix |
| dry_run | no | "false" | Compute buckets but don’t write patches |
| cleanup_patches | no | "false" | Delete patch_dir after a successful run |
| create_prs | no | "true" | Create/update one PR per bucket |
| github_token | no | "" | Token used for pushing branches + GitHub API (defaults to env GITHUB_TOKEN) |
| base_branch | no | "" | Base branch for PRs (defaults to repo default branch) |
| branch_prefix | no | codemods/ | Prefix for created branches |
| commit_message | no | chore: automated changes | Commit message for bucket PRs |
| pr_title | no | chore: automated changes ({owners}) | PR title template ({owners}, {bucket_key}) |
| pr_body | no | (see action.yml) | PR body template ({owners}, {bucket_key}, {files}) |
| draft | no | "false" | Create PRs as drafts |

$3

| Name | Description |
| -------------- | ------------------------------------------------- |
| matrix_json | JSON for strategy.matrix ({ include: [...] }) |
| buckets_json | Full buckets JSON (owners + files + matched rule) |
| prs_json | If create_prs=true, list of created/updated PRs |

$3

`yaml
- name: Bucketize (patches + matrix)
id: split
uses: anatoliisf/split-by-codeowners@v1
with:
draft: "true"

- name: Use matrix
run: echo '${{ steps.split.outputs.matrix_json }}'
`

$3

At minimum:

`yaml
permissions:
contents: write
pull-requests: write
`

CLI

The CLI operates on your current working tree (modified + untracked files) and groups them by CODEOWNERS.

$3

`bash
npx split-by-codeowners --help
`

$3

#### Common

- --repo-path : Repo root path (relative to current working directory)
- --codeowners : Path to CODEOWNERS file (default: CODEOWNERS)
- --exclude : File containing newline-separated glob patterns to exclude, or - to read from stdin
- --include-unowned : Include files with no owners in an __UNOWNED__ bucket (default: true)
- --unowned-bucket-key : Bucket key for unowned files (default: __UNOWNED__)
- --max-buckets : Fail if number of buckets exceeds n (default: 30)
- --patch-dir