repo-scaffold

A modern project scaffolding tool that helps you quickly create standardized project structures with best practices.

Features

🚀 Quick project initialization with modern best practices
📦 Cookiecutter templates with standardized structure
⚙️ Interactive project configuration
🔧 Pre-configured development tools (ruff, pytest, just)
📚 Documentation setup with MkDocs Material
🔄 GitHub Actions workflows included
🏷️ Conventional-commit driven versioning via Cocogitto
📦 Dependency / workspace management with uv

Installation

# Recommended: install as a uv tool
uv tool install repo-scaffold

# Or run without installing
uvx repo-scaffold list

# Or with pip
pip install repo-scaffold

Quick Start

# List available templates
repo-scaffold list

# Create a new project (interactive)
repo-scaffold create python

# Create a project in a specific directory, no prompts
repo-scaffold create python --no-input -o ./my-projects

# Create a uv workspace monorepo
repo-scaffold create uv-workspace -o ./my-projects

# Push a generated project to GitHub: create the repo, set CI secrets,
# push the initial commit, create the gh-pages branch, and point GitHub
# Pages at it. Reads GITHUB_TOKEN from the environment.
export GITHUB_TOKEN=ghp_...
repo-scaffold gh-init ./my-projects/my-python-project

See the GitHub bootstrap docs for the full flag list and the secrets/variables gh-init knows how to set.

End-to-End: From `create` to GitHub Pages

A full walkthrough from an empty directory to a published repository with CI and docs.

# 1. Generate the project. `create` also runs `git init` on branch `master`
#    (opt out with --no-git). Drop --no-input to configure it interactively.
repo-scaffold create python --no-input -o ./workspace
cd ./workspace/my_python_project   # directory name is the project_slug

# 2. (Optional) make your own first changes here. gh-init creates the
#    initial commit for you, so an extra commit at this point is optional.

# 3. Provide a GitHub token with `repo` scope (or `public_repo` for public repos).
export GITHUB_TOKEN=ghp_...

# 4. Bootstrap GitHub. By default gh-init will:
#      - create the repository (name/description pulled from pyproject.toml)
#      - set the CI secrets/variables the generated workflows expect
#      - push the initial commit to `master`
#      - create the `gh-pages` branch and set it as the GitHub Pages source
repo-scaffold gh-init .

# 5. Publish docs: push a release tag (or let the Cocogitto version-bump
#    workflow create one). The docs-deploy workflow builds the site and
#    pushes it to `gh-pages`, which GitHub Pages now serves automatically.
git push --tags   # or: git tag 0.1.0 && git push origin 0.1.0

Common opt-outs:

repo-scaffold create python --no-git — skip the local git init.
repo-scaffold gh-init . --private — create a private repository.
repo-scaffold gh-init . --protect-branch — protect the default branch (require PR review; admins can still push so releases keep working).
repo-scaffold gh-init . --no-push — create the repo and set secrets without pushing (Pages setup is skipped, since it needs the pushed branch).
repo-scaffold gh-init . --no-pages — push, but don't create gh-pages or configure Pages (you can set it later in repo Settings → Pages).

Available Templates

Currently supported project templates:

python — single-package Python project
- pyproject.toml + uv for dependency management
- pytest + coverage, ruff for lint & format
- Optional Click CLI, Podman compose files, GitHub Actions, MkDocs Material docs
- Cocogitto release workflow that bumps version, writes CHANGELOG.md, tags, and triggers PyPI publish
uv-workspace — uv workspace monorepo
- Workspace-aware pyproject.toml with one initial member under packages/
- Shared dev / docs dependency groups
- Cocogitto monorepo release workflow with per-package and global tags
- Same lint / test / docs tooling as the python template

Both templates use just (via rust-just) as the task runner. Bootstrap from a clean machine with uvx --from rust-just just init — that recipe also installs rust-just as a uv tool, so every subsequent recipe can be run as plain just <recipe>.

Development Setup

# Clone the repository
git clone https://github.com/ShawnDen-coder/repo-scaffold.git
cd repo-scaffold

# Bootstrap once: installs rust-just as a uv tool, syncs deps, installs hooks
uvx --from rust-just just init

# Subsequent runs use `just` directly
just lint
just test

Releasing

This project (and the templates it generates) uses Cocogitto driven by conventional commits:

Push a feat: / fix: / breaking-change commit to master and the version-bump workflow runs cog bump --auto, updating CHANGELOG.md, bumping pyproject.toml via uv version, committing, and tagging.
The release workflow then builds and publishes the tagged version.

See cog.toml for hook and changelog configuration.

Metadata

Release files for repo-scaffold 0.21.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for repo-scaffold 0.21.0
File	Size	Uploaded
repo_scaffold-0.21.0.tar.gz	85.9 kB	Jul 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for repo-scaffold 0.21.0
File	Interpreter	ABI	Platform	Reset
repo_scaffold-0.21.0-py3-none-any.whl 116.4 kB Jul 14, 2026	Python 3	none	any	Details

Total release size: 202.3 kB

Release files / repo_scaffold-0.21.0.tar.gz

Download URL	repo_scaffold-0.21.0.tar.gz
Size	85.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`bda8ef11a5dd2850b66af111652dfc66260dfc3ca3f99b474b7eda1a8b89b2e4`
BLAKE2b-256 checksum How to use checksums	`263af4212a72592929c78280a6e5e58f78207b203138bc17fde13194d036bc04`
Upload date	Jul 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / repo_scaffold-0.21.0-py3-none-any.whl

Download URL	repo_scaffold-0.21.0-py3-none-any.whl
Size	116.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d99770a97dd45fd3cc8a35ae53b2c0f3fed822a0ef739d776d4117bd2db1a458`
BLAKE2b-256 checksum How to use checksums	`22081f93d76d27463cef05628b47fab52cdbda0ddfe849016e89fb4e22269a04`
Upload date	Jul 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`