PushForge

PushForge turns publishing a local project to GitHub into one command.

pipx install pushforge

cd my-project

pushforge

No git init. No GitHub repository setup. No remote configuration. No copy/paste commands. No repeated authentication.

Just:

pushforge

A cross-platform DevSecOps CLI for one-command project publishing and GitHub automation — not merely "a GitHub uploader."

Code → PushForge → Detect → Secure → Git → GitHub → CI/CD → Deployment

Highlights

• One install. pipx install pushforge
• One GitHub connection. Keep logged in once; every project after that is one command.
• One command per project. pushforge works in a brand-new or existing project.
• Security-first. Automatic secret scanning blocks accidental credential leaks before they ever reach GitHub.
• Smart detection. Identifies your stack and generates a tailored .gitignore and a starter README.
• CI from day one. pushforge pipeline writes a GitHub Actions workflow matched to your stack.
• Safe by design. Never force-pushes by default, never overwrites repositories, never stores credentials in project files.

How it works

Running pushforge inside any project:

✓ GitHub account connected            (only the first time)
✓ Project detected                    Python / FastAPI
✓ .gitignore generated
✓ README generated                    (when the project has none)
✓ Security scan completed
✓ Git repository initialized
✓ GitHub repository created
✓ Initial commit created
✓ Remote origin configured
✓ Code pushed successfully

🚀 Project pushed successfully!

Repository:
https://github.com/you/my-project

Everything is incremental and safe:

Installation

Requirements

• Python 3.11+
• git available on PATH

Recommended — pipx

pipx install pushforge

pipx isolates the tool and puts the pushforge command on your PATH (works in any folder).

Or pip

pip install --user pushforge

Verify the install works globally (from any directory):

pushforge --version

Per-OS install notes

Linux / macOS — pipx (recommended)

sudo apt install pipx          # Debian/Ubuntu — or: brew install pipx
pipx install pushforge
pipx ensurepath                # one-time, adds ~/.local/bin to PATH

No pipx? Use pip with --user:

pip install --user pushforge

No pipx? Use the venv + symlink pattern (works for any user; the entry point lands on PATH in ~/.local/bin):

git clone https://github.com/aasz253/PushForge
cd PushForge
python3 -m venv ~/.local/share/pushforge-venv
~/.local/share/pushforge-venv/bin/pip install .
ln -s ~/.local/share/pushforge-venv/bin/pushforge ~/.local/bin/pushforge

Windows — PowerShell

git clone https://github.com/aasz253/PushForge
cd PushForge
py -m venv "$env:LOCALAPPDATA\pushforge-venv"
& "$env:LOCALAPPDATA\pushforge-venv\Scripts\python.exe" -m pip install .
New-Item -Type Directory -Force "$env:LOCALAPPDATA\Programs" | Out-Null
Copy-Item "$env:LOCALAPPDATA\pushforge-venv\Scripts\pushforge.exe" "$env:LOCALAPPDATA\Programs\pushforge.exe"
# Add "$env:LOCALAPPDATA\Programs" to your PATH if missing:
#   start ms-settings:appsfeatures (Settings → "Edit environment variables")

Once installed on any OS, PushForge works from any folder:

cd /any/folder
pushforge            # works everywhere

Quick start

1. Connect GitHub (once)

pushforge auth login

You will never be asked for your GitHub password. PushForge uses:

• the GitHub CLI device-flow login when gh is installed, or
• the GitHub OAuth device flow (set PUSHFORGE_CLIENT_ID to your GitHub App client ID to use it directly), or
• an existing GH_TOKEN / GITHUB_TOKEN environment variable.

Credentials are stored in your operating system's secure keyring (or a user-only permission file), never inside a project.

Check the state at any time:

pushforge auth status

2. Publish a project

cd ~/projects/ai-knowledge-assistant
pushforge

That's it. A commit is created on main and pushed to a new (or existing) GitHub repository matching the project name.

Fresh-machine smoke test

Everything above works identically on a brand-new laptop — no hidden config, no extra setup. This is the 5-minute verification path:

# 1. Tooling
sudo apt install pipx gh          # or: brew install pipx gh
pipx ensurepath && exec $SHELL

# 2. Install from PyPI (always the latest build)
pipx install pushforge

# 3. Connect GitHub once (uses gh; falls back to OAuth device flow)
pushforge auth login

# 4. Real publish test
mkdir ~/test-app && cd ~/test-app
echo "from fastapi import FastAPI" > main.py
echo -e "fastapi\npytest" > requirements.txt
pushforge                        # detect → secure → gitignore → README → repo → commit → push

# 5. Bonus checks
pushforge pipeline               # CI/CD workflow for your stack
pushforge scan                   # secret scan

The full pipeline above — detection, security scan, .gitignore, README, repository creation, commit and push — runs with a single pushforge.

Authentication

If you run pushforge without authentication, the setup flow launches automatically and the original operation resumes once you're connected.

Tokens are never printed, never written to .env, never committed, and never appear in error messages.

Commands

pushforge                     # One-command publish
pushforge auth login|status|logout
pushforge scan                # Scan project for secrets
pushforge status              # Project / repo / auth summary
pushforge pipeline            # Generate a CI workflow for the detected stack
pushforge readme              # Generate a README (skips existing)
pushforge config              # View or update configuration
pushforge version             # Show version

Options for pushforge

pushforge --private            # private repository
pushforge --public             # public repository (default)
pushforge --name my-repo       # override repository name
pushforge -m "feat: init"      # custom commit message
pushforge --description "..."  # repository description
pushforge --force              # push with --force-with-lease (explicit opt-in)
pushforge --force-remote       # replace an existing origin remote
pushforge --skip-security      # disable the secret scan (not recommended)
pushforge --level strict       # stricter secret scanning
pushforge --dry-run            # preview without changing anything

Auto-generated README

When a project has no README, pushforge writes a compact README.md with the detected stack, badge, and quick-start commands. Existing READMEs are never touched. Control it with:

pushforge config --auto-readme    # on (default) / --no-auto-readme
pushforge readme                  # generate or preview a README on demand

pushforge pipeline

Generates a .github/workflows/ci.yml matched to the detected stack (Python, Node/React, Go, Rust, Java, Docker, Terraform, or a generic fallback). It never overwrites without --force:

pushforge pipeline                       # write .github/workflows/ci.yml
pushforge pipeline --dry-run             # preview which workflow applies
pushforge pipeline --name unit-tests     # different file name
pushforge pipeline --force               # overwrite an existing workflow

Security model

Before any push, PushForge scans your project and looks for:

• API keys (AWS, Google, Stripe, GitHub, Slack…)
• private key material (-----BEGIN … PRIVATE KEY-----, *.pem, *.key)
• database connection strings with embedded credentials
• .env and credential files
• high-entropy token assignments in source files

If a likely secret is found, the push is blocked:

⚠ Potential secret detected

File:   config.py:12
Finding: AWS access key

Push blocked to protect your credentials.
Remove the secret and try again.

Secret values are never displayed — at most a non-reversible fingerprint is.

PushForge also never:

• force-pushes unless you pass --force (and then it uses --force-with-lease)
• overwrites an existing GitHub repository
• overwrites an existing .gitignore (it only appends missing rules)
• swaps an existing remote without --force-remote
• auto-deletes data

Repository naming & visibility

• Names are suggested from the directory name and normalized (e.g. ~/Projects/AI Assistant → ai-assistant).
• Default visibility is public; override per-project with --private / --public, or persist a preference:

pushforge config --visibility private

Configuration

pushforge config                                     # show current config
pushforge config --visibility private
pushforge config --branch trunk
pushforge config --commit-message "chore: sync"
pushforge config --security-level strict
pushforge config --username octocat
pushforge config --no-auto-readme                    # disable README generation

Environment overrides (PUSHFORGE_VISIBILITY, PUSHFORGE_BRANCH, PUSHFORGE_CLIENT_ID) take precedence over stored values. Configuration lives in your user config directory, never in a project.

Supported platforms

• Linux (Debian/Ubuntu, Fedora, Arch and derivatives)
• macOS (Intel and Apple Silicon)
• Windows (PowerShell and Command Prompt)

Paths are handled with Python's platform-independent APIs.

Stack detection

PushForge recognizes common markers out of the box:

Detection powers tailored .gitignore + README generation and the pushforge pipeline command (GitHub Actions workflows), with foundation for future DevSecOps automation (dockerize, deploy, secure).

Architecture

src/pushforge/
├── cli.py            # Typer CLI surface
├── workflow.py       # ordered publish pipeline
├── github/           # auth, API client, repository ops
├── git/              # manager, remotes, commits
├── detection/        # stack detection + .gitignore + README
├── cicd/             # CI/CD workflow (pipeline) generation
├── security/         # secret patterns + scanner
├── config/           # user configuration
├── templates/        # .gitignore templates
└── ui/               # Rich terminal rendering

GitHub API logic is separate from Git operations; authentication is separate from repository creation; the security scanner is CLI-independent. Components are injected so they can be tested independently.

Roadmap

• pushforge dockerize — add Dockerfile/docker-compose generation
• pushforge deploy — deploy targets for common platforms (GitHub Pages first)
• pushforge secure — deep dependency & configuration auditing
• pushforge ai — LLM-assisted commit messages, security explains
• Native installers and package managers

The MVP works entirely without AI; these features are designed to be added without rewriting the core.

Development

git clone https://github.com/aasz253/PushForge
cd PushForge

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

pytest
ruff check .
ruff format --check .
mypy src/pushforge
bandit -r src/ -c pyproject.toml

Contributing

See CONTRIBUTING.md. All contributions must pass lint, type-checking, the test suite, and a security scan.

Security policy

See SECURITY.md for reporting vulnerabilities. Never open a public issue with credentials or tokens.

License

MIT

Forge your code. Push anywhere. ⚒ Created by Sifuna Codex