FINI template-repo

A good template for github repos with best practices adoption.

Template Features

GitHub Community Standards

• ✅ All github community standards are checked off
  • ✅ This README with badges and banner
  • ✅ Contributor Covenant-based Code of Conduct
  • ✅ Contributing Guide includes a step-by-step guide to our command line development process
  • ✅ GPL2 license
  • ✅ Security Policy
  • ✅ Issue Templates
  • ✅ PR Template
• ✅ gitattributes based on gitattributes
• ✅ gitignore with comments
• ✅ CODEOWNERS that is self-documented

Modular Justfile Architecture

The justfile imports 11 modules from the .just/ directory for a clean, maintainable workflow:

• ✅ gh-process.just - Complete PR lifecycle automation with smart check polling and AI review integration
• ✅ compliance.just - Repository health checks validating all GitHub community standards and branch protection
• ✅ shellcheck.just - Bash script linting that extracts and validates all scripts in just recipes
• ✅ cue-verify.just - Three-stage validation of .repo.toml structure, flags, and GitHub sync
• ✅ claude.just - Claude Code permission management with canonical sorting and structure validation
• ✅ copilot.just - Interactive Copilot suggestion picker, review refresh, and backup/rollback for applied suggestions
• ✅ repo-toml.just - Metadata extraction that generates shell variables from repository configuration
• ✅ template-sync.just - Safe template updates preserving local customizations via multi-version checksums
• ✅ testing.just - Automated test recipes for PR body logic and template sync functionality
• ✅ clean-template.just - Strips template documentation and files for new repos
• ✅ pr-hook.just - Optional pre-PR hooks for project-specific automation

Repository Metadata System

• ✅ .repo.toml - Centralized configuration with description, topics, URLs, and feature flags
• ✅ Cue schema validation - Three-stage verification checks structure, validates flags against actual files, and syncs GitHub metadata
• ✅ Automatic shell variable generation - The repo_toml_generate recipe exports TOML data as sourceable bash variables
• ✅ GitHub metadata synchronization - cue-sync-from-github pulls description and topics from GitHub API

GitHub Actions

Thirteen workflows handle automation and quality, all hardened with StepSecurity Harden-Runner to prevent supply chain attacks:

• ✅ Auto-assign - Automatically assigns issues and PRs to maintainers
• ✅ Checkov - Security scanning for GitHub Actions workflows with SARIF output
• ✅ Markdownlint - Enforces markdown standards across all docs
• ✅ Actionlint - Lints GitHub Actions workflow files
• ✅ Zizmor - Static security analysis for GitHub Actions workflows
• ✅ Claude mention integration - Mentions Claude AI when appropriate
• ✅ Claude Code review - AI-powered code review automation
• ✅ Cue verification - Validates .repo.toml format and flags
• ✅ Dependency Review - Scans PRs for vulnerable dependency versions
• ✅ OpenSSF Scorecard - Automated security posture assessment with badge
• ✅ Checksums Verification - Verifies CHECKSUMS.json matches all tracked files
• ✅ PR Body Tests - Tests PR body update logic on every PR
• ✅ Template Sync Tests - Tests template synchronization system

AI-Enhanced Development

• ✅ Conditional AI review display - After PR checks complete, shows review comments based on .repo.toml flags
• ✅ GitHub Copilot review integration - Enable/disable with copilot-review flag
  • Interactive suggestion picker (just copilot_pick) with diff preview and one-key apply
  • Review refresh (just copilot_refresh) with gum spin progress and completion detection
  • Backup and rollback (just copilot_rollback) for safely reverting applied Copilot suggestions
• ✅ Claude Code review integration - Enable/disable with claude-review flag
• ✅ Smart polling system - Waits up to 30 seconds for checks to start, then polls every 5 seconds for faster feedback

Automated Testing

• ✅ PR body update tests - Validates PR description generation logic with fixture-based test cases
• ✅ Template sync tests - Tests safe template update system with fixture scenarios
• ✅ Shared utility library - Cross-platform checksum computation used by template sync

Additional Features

• ✅ Priority labels - Extra issue labels for better organization
• ✅ Prerequisites installation - Script to install required tools
• ✅ Pre-commit hooks - Enforces code quality and formatting before commits
• ✅ Release automation - just release <version> creates GitHub releases with auto-generated notes and age monitoring

Usage

1. To use this template, you can create a new repository by clicking on "Use this template" button.
2. Remember to replace any chicks-net, fini-net, and template-repo references with the right values for your project. (Github templates do not offer variable substitution, but we still have to call them templates for some reason.)
3. Ditch the "Template Status", "Usage", and "Kudos" sections in the README.md. just clean_template will give you a clean /README.md, and remove other files that are not required.

Here is a nice checklist of things to consider with a new repo.

Keeping Your Derived Repo Up-to-Date

Pull updates to .just/ modules from template-repo:

just update_from_template

Only unmodified files are updated. Local customizations are preserved.

Preview changes:

just checksums_verify              # Check which files would update
just checksums_diff .just/gh-process.just  # See specific changes

The update system uses multi-version checksum tracking to safely identify which files match known template versions. Files with local modifications are skipped and reported.

Contributing

• Code of Conduct
• Contributing Guide includes a step-by-step guide to our development process.

Support & Security

• Getting Support
• Security Policy

License

I went with the GPL2 license, but the MIT license is also worth considering.

Other good template repos on github

• Jose Gracia Berenguer did a great job with their project-template repo. This looks like a student project, but it is one of the best templates I've found on github.
• Cookiecutter Data Science is cool, but it isn't actually a template repo.
• gh-best-practices-template is doing great at checking off all of the boxes. They've including funding and citations which I haven't tried yet. I'm not a fan of how all of the Markdown files are in the root directory. I definitely prefer stuffing those under /.github for a cleaner root directory.

Thanks

• I've really enjoyed building projects with just.
• The GitHub CLI makes browser-free workflows not only possible, but fun.