repo-conventions

RepoConventions

RepoConventions is a .NET tool that runs convention scripts configured for a repository, committing any resulting changes and optionally opening a GitHub pull request.

Quick Start

Install the tool globally:

dotnet tool install --global repo-conventions

Or run it ad hoc with dnx:

dnx repo-conventions

To add a convention to the current repository:

repo-conventions add Faithlife/CodingGuidelines/conventions/gitattributes-lf

That command creates .github/conventions.yml if it does not already exist:

conventions:
  - path: Faithlife/CodingGuidelines/conventions/gitattributes-lf

Commit the configuration file, then apply the convention from the repository root:

repo-conventions apply

To add the reference, apply it, commit the changes, push a branch, and open a GitHub pull request in one run:

repo-conventions add Faithlife/CodingGuidelines/conventions/gitattributes-lf --open-pr

Configuration

RepoConventions reads .github/conventions.yml from the target repository root by default. Use --config <path> to use a different file. Relative config paths are resolved from the current process directory.

A configuration file is a YAML mapping with these top-level properties:

Property	Required	Description
conventions	Yes	Sequence of convention references, applied in declaration order.
pull-request	No	Default pull request metadata used only when running with --open-pr.

Complete example:

conventions:
  - path: Faithlife/CodingGuidelines/conventions/dotnet-sdk
    settings:
      version: 10
  - path: ./conventions/local-policy
    pull-request:
      labels:
        - dependencies

pull-request:
  labels:
    - automation
  reviewers:
    - octocat
  assignees:
    - octocat
  draft: true
  auto-merge: false
  merge-method: squash

Convention References

Each item in conventions must contain a non-empty path. It may also contain settings and pull-request.

path identifies a convention directory. Each convention should document its own settings, behavior, and required tools.

Supported path forms:

Form	Meaning
owner/repo/path@ref	Clone a GitHub repository and use path inside it. path may be omitted to use the repository root. @ref may be omitted to use the repository default branch.
./relative/path	Resolve relative to the YAML file that contains the reference.
../relative/path	Resolve relative to the YAML file that contains the reference. The result must stay inside that YAML file's repository.
/root/relative/path	Resolve from the root of the repository that contains the YAML file.

settings is passed to the convention as JSON-compatible data. Use YAML objects, arrays, strings, numbers, booleans, or null values. Each convention documents the settings it accepts.

conventions:
  - path: Faithlife/CodingGuidelines/conventions/dotnet-sdk
    settings:
      version: 10

Pull Request Settings

Pull request settings are used only when the command runs with --open-pr.

Supported properties:

Property	Type	Description
labels	string sequence	Labels to add to the generated pull request. Missing labels are created automatically. RepoConventions always also adds the repo-conventions label.
reviewers	string sequence	GitHub users or teams to request as reviewers. Team reviewers use GitHub's org/team form.
assignees	string sequence	GitHub users to assign.
draft	boolean	When true, create the pull request as a draft.
auto-merge	boolean	When true, enable GitHub auto-merge after opening or updating the pull request.
merge-method	string	Preferred auto-merge method: merge, squash, or rebase. Defaults to squash when auto-merge is enabled and no single method is configured.

Pull request settings can appear at three levels:

• Top-level pull-request settings apply to the whole generated pull request.
• A top-level convention reference's pull-request settings apply only if that convention contributes commits to the generated pull request.
• A convention's own convention.yml can provide default pull-request settings for that convention, whether the convention is stored in the target repository or cloned from a remote repository. Reference-level settings supplement list values and override scalar values.

RepoConventions de-duplicates labels, reviewers, and assignees case-insensitively while preserving the first spelling it sees. Convention-level PR metadata is ignored for conventions that do not create commits during the run.

CLI flags override configured PR settings for a single run:

• --draft and --no-draft override draft.
• --auto-merge and --no-auto-merge override auto-merge.
• --merge-method merge|squash|rebase overrides merge-method.

When auto-merge is enabled, RepoConventions does not request reviewers or assignees. If a requested merge method is disabled or rejected by GitHub, RepoConventions tries other allowed methods, preferring squash as the first fallback. If auto-merge was enabled by configuration and cannot be enabled, the command reports the failure but still succeeds. If --auto-merge was provided explicitly and auto-merge cannot be enabled, the command fails.

CLI Reference

RepoConventions has two commands:

repo-conventions add <path> [<path>...] [options]
repo-conventions apply [options]

Common path options:

Option	Description
--repo <path>	Target repository root. Defaults to the current directory. Relative paths are resolved from the current process directory.
--config <path>	Conventions configuration file. Defaults to .github/conventions.yml under the target repository root. Relative paths are resolved from the current process directory.
--temp <path>	Temporary root for RepoConventions-managed transient files. Defaults to the system temp directory. Relative paths are resolved from the current process directory.

Common pull request options:

Option	Description
--open-pr	Apply conventions, create commits, push a repo-conventions branch, and open or update a pull request.
--draft / --no-draft	Override configured draft behavior. These options cannot be used together.
--auto-merge / --no-auto-merge	Override configured auto-merge behavior. These options cannot be used together.
--merge-method <method>	Preferred auto-merge method. Must be merge, squash, or rebase.
--git-no-verify	Pass --no-verify to git commit and git push commands run by RepoConventions.

add

repo-conventions add appends one or more convention paths to the configuration file. If the file is missing, it creates it. If a path is already present, it leaves the file unchanged for that path. If settings are required, they must be added by hand to the configuration file.

Examples:

repo-conventions add Faithlife/CodingGuidelines/conventions/dotnet-sdk
repo-conventions add ./conventions/local-policy
repo-conventions add ./conventions/dotnet-sdk ./conventions/github-actions
repo-conventions add ./conventions/local-policy --repo ../target-repo --config ../target-repo/.config/repo-conventions.yml

add requires the target repository path to be a Git repository root. Unless --open-pr is used, it can run when the target repository has tracked or untracked file changes.

With --open-pr, add commits any newly added convention references, applies the resulting configuration, commits convention changes, and opens or updates a pull request:

repo-conventions add ./conventions/local-policy --open-pr --git-no-verify

apply

repo-conventions apply loads the configuration file, resolves the full convention plan, applies each convention in order, and creates commits for conventions that leave changes behind.

Examples:

repo-conventions apply
repo-conventions apply --git-no-verify
repo-conventions apply --repo ../target-repo --config ../target-repo/.config/repo-conventions.yml --temp ../target-repo/.artifacts/repo-conventions-temp

apply requires no tracked or untracked file changes in the target repository before it starts. More precisely, git status --porcelain --untracked-files=normal must produce no output. Ignored files do not matter.

With --open-pr, apply pushes convention commits and opens or updates a GitHub pull request:

repo-conventions apply --open-pr
repo-conventions apply --open-pr --draft
repo-conventions apply --open-pr --no-draft
repo-conventions apply --open-pr --auto-merge --merge-method rebase
repo-conventions apply --open-pr --no-auto-merge

--open-pr requires:

• no tracked or untracked file changes in the target repository, as reported by git status --porcelain --untracked-files=normal
• a non-detached starting branch
• no unpushed commits on the starting branch
• the GitHub CLI gh installed and authenticated

When opening a pull request, RepoConventions creates repo-conventions, repo-conventions-2, or the next available suffix. If an open RepoConventions pull request already targets the starting branch, the command updates that pull request instead of opening another one. If the base branch has advanced, the existing PR branch is rebuilt from the current base and force-pushed.

Commit Behavior

When a convention changes files, RepoConventions commits those changes. A convention can also create its own commits. If a convention makes no changes, no commit is added for that convention.

Writing Conventions

For the convention authoring contract, examples, idempotency expectations, script execution details, and agent-friendly workflow, see skills/create-repo-conventions/SKILL.md.