auto-pr

Auto-create pull requests from conventional commits on ai/* branches. Parses commit messages, fills a PR template, and optionally uses an AI provider (GitHub Models by default in CI; local OpenAI-compatible servers for self-hosted or dev) to generate descriptions for multi-commit PRs.

Convention over configuration. Run npx -p github:knirski/auto-pr auto-pr-init, set up a GitHub App, and you're done — most adopters only use GitHub Actions and do not add this package to package.json unless they want the CLIs locally. Defaults work for most projects; override via workflow inputs only when needed.

Universal: Works with any GitHub project — Node, Python, Rust, Go, etc. No package.json required when using the reusable workflows (generate + create). No action copying — workflows fetch everything from knirski/auto-pr. No Nix required — users use Node/npx only.

Goal: Enable AI-assisted development workflows. When an AI agent (or developer) pushes to an ai/-prefixed branch, a workflow automatically creates or updates a PR with a title and body derived from conventional commits. For 2+ commits, the AI provider summarizes the changes into a coherent description.

Table of contents

• Features
• How it works
• Quick start
• Commands
• Documentation
• License

Features

• Conventional commits — Parses feat:, fix:, docs:, etc. for PR title and type
• PR template — Fills .github/PULL_REQUEST_TEMPLATE.md with description, changes, checklist
• AI integration — For 2+ commits, summarizes commit bodies into a PR description via local (OpenAI-compatible HTTP, e.g. llama.cpp) or github-models
• gh CLI — Thin wrapper around gh pr create / gh pr edit
• CI-agnostic — get-commits appends paths and count to GITHUB_OUTPUT; generate-content writes pr-title.txt and pr-body.md under the workspace. Works with GitHub Actions or any orchestrator that sets the same env conventions.

How it works

1. Get commits — auto-pr-get-commits runs git log and git diff to produce commits.txt, files.txt, and outputs paths to GITHUB_OUTPUT
2. Generate content — auto-pr-generate-content parses commits, counts semantic commits. For 1 commit: fills template from body. For 2+: calls the AI provider to summarize, then fills template. Writes pr-title.txt and pr-body.md under {GITHUB_WORKSPACE}
3. Create or update PR — auto-pr-create-or-update-pr reads those files, then runs gh pr view → gh pr edit or gh pr create

Merge commits are filtered out. Non-conventional commits are included; type falls back to "Chore".

Quick start

Users (adopters)

Add auto-pr to any repo in 6 steps:

1. Init — npx -p github:knirski/auto-pr auto-pr-init (creates workflow, PR template, and .nvmrc)
2. Create — GitHub App with Contents and Pull requests (Read and write)
3. Generate — Private key in app settings → save .pem
4. Install — Install the app on your repository
5. Secrets — Add APP_ID and APP_PRIVATE_KEY to Settings → Secrets and variables → Actions
6. Test — git checkout -b ai/test && git commit --allow-empty -m "chore: test" && git push

No package.json required. Full guide: docs/INTEGRATION.md.

Contributors

bun install
bun x lefthook install
bun run check

For local runs of workflow CLIs or run-auto-pr, copy .env.example to .env and set variables. The authoritative list is the environment table at the top of src/auto-pr/config.ts.

Command	Purpose
bun run check	Local checks (Bun, statix, deadnix, typos, lychee, actionlint)
bun run check:code	Code only: build, audit, unit tests, lint, knip, typecheck. Runs on pre-push (no integration).
bun run test:all	bun test then test:integration (integration needs env)
bun run act	check + integration jobs in Docker (gh act or nektos act; on Linux, Nix can supply act via nix run .#act)
bun run act -- check / bun run act -- integration	Only CI check, or only integration — see CONTRIBUTING.md
bun run check:with-links	Full check + lychee link verification (can fail on broken external URLs)
bun run check:just-links	Lychee link check only (requires lychee or Nix)

See CONTRIBUTING.md for full setup, Nix flake, and pre-push hooks.

Commands

Command	Purpose
npx auto-pr-get-commits	Get commit log and changed files; append commits, files, count to GITHUB_OUTPUT
npx auto-pr-generate-content	Generate PR title and filled body (AI for 2+ commits)
npx auto-pr-create-or-update-pr	Create or update PR via gh
npx auto-pr-fill-pr-template	CLI for filling PR template from commits (standalone use)
npx auto-pr-init	Create workflow, PR template, and .nvmrc in current repo

After install, or for one-offs: npx -p github:knirski/auto-pr <command>. CI runs the same bins via reusable workflows without a repo dependency.

Documentation

Audience	Documents
Users	Integration guide · Troubleshooting · PR template
Contributors	Architecture · CI & workflows · Contributing · Workflow security
Decisions	Architecture Decision Records
Project	Security · Support · Code of Conduct · CII badge progress

Full index: docs/README.md

This project was developed with assistance from AI coding tools.

License

Apache-2.0