An AI-driven release commander for open-source projects on GitHub.
Scan, commit, push, create repositories, tag releases, and audit readiness—in verifiable steps.

中文说明 · AI install guide · Execution protocol · Contributing

---

What it is

GitPilot is a skill package for AI assistants. It splits "let the AI publish my project" into deterministic, verifiable steps:

• Scripts do the mechanical work — scanning, grouping, committing, pushing, tagging, calling the GitHub API.
• The AI does the judgement and prose — commit messages, README content, release notes.

It has zero third-party dependencies: only Python 3.8+ and your local git. No gh CLI, no Docker, no pip install.

your intent → inspect & scan → plan commits → verify → publish → report facts
                 scripts          AI       scripts      API      JSON

Features

Capability	Command
Environment & repo health check	gitpilot.py doctor
Store / verify a GitHub token	gitpilot.py auth --token <TOKEN>
Initialise a local repository	gitpilot.py init
Scan for changes, secrets, oversized files	gitpilot.py scan
Plan how to split changes into commits	gitpilot.py group
Draft a conventional commit message	gitpilot.py msg
Commit by group / path	gitpilot.py commit
Smart push (retry + diagnostics)	gitpilot.py push
Infer the next semver from commits	gitpilot.py version
Generate release notes	gitpilot.py notes
Tag, push and publish a GitHub Release	gitpilot.py release
Open-source readiness score (0–100)	gitpilot.py audit
Create / update remote repositories	gitpilot.py repo create|info|update|topics|delete
Orchestrate many projects at once	gitpilot.py batch / board
Generate README, LICENSE, CI, issue templates	scaffold.py

Every command supports --json. Human-readable hints go to stderr; stdout carries data only, so an AI can always parse the result without guessing.

Requirements

• Python 3.8 or newer
• git on PATH
• A GitHub Personal Access Token — only needed for remote operations (create repo, push, release). Fine-grained token with Contents, Issues, Pull requests, Metadata.

Installation

Option 1 — user-level skill directory (recommended)

Copy the whole gitpilot/ folder into ~/.workbuddy/skills/, then verify:

PY="C:/Users/35680/.workbuddy/binaries/python/versions/3.13.12/python.exe"   # or: python3
GP="$HOME/.workbuddy/skills/gitpilot/scripts/gitpilot.py"

"$PY" "$GP" doctor --json
"$PY" "$(dirname "$GP")/selftest.py"     # expect: 35/35 passed

Keep the directory intact — gitpilot.py imports ghapi.py from the same scripts/ folder.

Option 2 — from the packaged zip

python -c "
import zipfile, pathlib
dst = pathlib.Path.home()/'.workbuddy'/'skills'
dst.mkdir(parents=True, exist_ok=True)
zipfile.ZipFile('gitpilot.zip').extractall(dst)
"

Configure credentials (only for remote operations)

"$PY" "$GP" auth --token ghp_xxxxxxxxxxxx

The token is stored in ~/.gitflow/credentials.json. You can also just export GITHUB_TOKEN. Never commit a token into a repository.

Quick start

# 1. Health check
"$PY" "$GP" doctor --json

# 2. Inspect the project: changes, leaked secrets, oversized files
"$PY" "$GP" scan --path /path/to/project --json

# 3. Fill in the open-source files (README, LICENSE, CI, templates)
"$PY" "$SCAF" --path /path/to/project --license mit --desc "one-line summary" --topics "cli,git"

# 4. See how changes should be split
"$PY" "$GP" group --path /path/to/project --json

# 5. Commit (secret scan runs automatically and blocks on hits)
"$PY" "$GP" commit --path /path/to/project --group 0 -m "feat(core): add parser" --json

# 6. Create the remote repo and push
"$PY" "$GP" repo create --name my-project --desc "one-line summary" --topics "cli,git" --license mit --link --json
"$PY" "$GP" push --path /path/to/project --json

# 7. Preview the release, then publish
"$PY" "$GP" release --path /path/to/project --json
"$PY" "$GP" release --path /path/to/project --apply --json

Safety by design

• scan runs before every commit and blocks on leaked credentials (exit code 3) or files ≥ 50 MB.
• release defaults to dry-run; publishing requires an explicit --apply.
• push --force requires --confirm-force; deleting a repo requires --confirm owner/repo.
• Tokens never appear in output — they are masked (ghp_****abcd) and stored outside repositories.
• Secrets, tokens and API keys are never written into generated files.

Project structure

gitpilot/
├── SKILL.md              skill metadata and workflows
├── agents/openai.yaml    UI metadata and invocation policy
├── PLAN.md               execution protocol
├── INSTALL_AI.md         AI installation and readiness guide
├── scripts/              CLI, GitHub client, scaffolder, self-tests
├── references/           commit, API, OSS and multi-project guides
├── assets/               brand artwork and registry template
└── .github/              CI and contribution templates

Testing

python scripts/selftest.py           # human-readable output
python scripts/selftest.py --json    # machine-readable summary
python scripts/selftest.py --keep    # keep the temp workspace for debugging

Covers correctness (version inference, grouping, notes, scoring, secret blocking), stability (missing token, no remote, non-git directory, empty repo, Unicode paths, renames) and efficiency (1000+ file repositories).

License

MIT — see LICENSE.