https://github.com/knirski/auto-pr
Auto-create PRs from conventional commits on ai/* branches. Parses commits, fills PR template with AI-generated summaries.
https://github.com/knirski/auto-pr
ai-assisted-development automation conventional-commits github-actions ollama pr-template pull-requests
Last synced: 2 months ago
JSON representation
Auto-create PRs from conventional commits on ai/* branches. Parses commits, fills PR template with AI-generated summaries.
- Host: GitHub
- URL: https://github.com/knirski/auto-pr
- Owner: knirski
- License: apache-2.0
- Created: 2026-03-14T09:04:37.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-01T23:50:05.000Z (2 months ago)
- Last Synced: 2026-04-02T07:41:51.844Z (2 months ago)
- Topics: ai-assisted-development, automation, conventional-commits, github-actions, ollama, pr-template, pull-requests
- Language: TypeScript
- Homepage: https://github.com/knirski/auto-pr
- Size: 7.51 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# auto-pr
[](https://github.com/knirski/auto-pr/actions)
[](https://app.codecov.io/gh/knirski/auto-pr)
[](https://scorecard.dev/viewer/?uri=github.com/knirski/auto-pr)
[](https://github.com/knirski/auto-pr/blob/main/package.json)
[](https://opensource.org/license/Apache-2.0)
[](https://github.com/sponsors/knirski)
[](https://liberapay.com/knirski/)
[](https://www.bestpractices.dev/en/projects/new?project_url=https%3A%2F%2Fgithub.com%2Fknirski%2Fauto-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](.github/workflows/auto-pr-generate-reusable.yml) (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](#features)
- [How it works](#how-it-works)
- [Quick start](#quick-start)
- [Commands](#commands)
- [Documentation](#documentation)
- [License](#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](https://github.com/settings/apps/new) 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](docs/INTEGRATION.md).
### Contributors
```bash
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`](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`; with Nix, `nix run .#act` on supported platforms — see [CONTRIBUTING.md](CONTRIBUTING.md)) |
| `bun run act -- check` / `bun run act -- integration` | Only CI `check`, or only `integration` — see [CONTRIBUTING.md](CONTRIBUTING.md#run-ci-locally-check-job) |
| `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](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 `. CI runs the same bins via reusable workflows without a repo dependency.
## Documentation
| Audience | Documents |
|----------|-----------|
| **Users** | [Integration guide](docs/INTEGRATION.md) · [Troubleshooting](docs/TROUBLESHOOTING.md) · [PR template](docs/PR_TEMPLATE.md) |
| **Contributors** | [Architecture](docs/ARCHITECTURE.md) · [CI & workflows](docs/CI.md) · [Contributing](CONTRIBUTING.md) · [Workflow security](docs/WORKFLOW_SECURITY.md) |
| **Decisions** | [Architecture Decision Records](docs/adr/) |
| **Project** | [Security](SECURITY.md) · [Support](SUPPORT.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [CII badge progress](docs/CII.md) |
Full index: [docs/README.md](docs/)
This project was developed with assistance from AI coding tools.
## License
[Apache-2.0](LICENSE)