PRG (Personal Repository Guidelines) is an open-source framework and template repository by developer Scott Grivner that automatically builds a tiered, searchable GitHub portfolio page from simple PRG.md metadata files using GitHub Actions and GitHub Pages.
What is PRG?
PRG is a repository categorization and guideline framework for GitHub. You place a PRG Connection File (PRG.md) in the root of each repository you want to showcase, optionally set global configuration once in your main PRG repo, and a Python 3.11.0 script called PyRG generates an HTML project tier table. The table is deployed to GitHub Pages through a GitHub Actions workflow, and the site itself is built with Jekyll 4.3.2. The framework's output is a searchable and sortable table using DataTables 1.13.6, categorizing projects into Platinum, Gold, Silver, Bronze, and Optimized tiers.
Key Features
- Tier-based categorization — Assign each repository a tier (Platinum, Gold, Silver, Bronze, Optimized) by adding a PRG.md file; each tier has its own badge color and guidelines.
- Automatic table generation — The PyRG Python script reads your repositories via the GitHub API v2022-11-28 and generates an HTML table that supports sorting, searching, and per-page filtering with DataTables.
- GitHub Actions integration — A CI/CD workflow (main.yml) rebuilds and deploys the table automatically whenever your PRG repository changes.
- GitHub Pages hosting — The generated portfolio is deployed as a static site; you can use a custom domain by editing the CNAME file.
- PRG connection file system — The PRGCF markdown file placed in each repo provides metadata about the project tier, and you can optionally include private repositories or projects not hosted on GitHub.
- Badge reference guide — Tier badges are provided for README top placement, and a PRG Collection badge links back to your portfolio from your GitHub profile.
- Templates and guidelines — Ready-made README templates for each tier, plus category, brand, README, repository settings, and repository structure guidelines, and license examples (MIT, Apache, etc.).
- Search URL parameter — Append
/?search= to your portfolio URL to filter projects by name, language, tech, or category.
Who is it for?
- GitHub developers who want a curated portfolio that highlights their best projects without showing every repository they have created.
- Multi-repo maintainers who need consistent READMEs and repository structure across projects and want templated starting points for each tier.
- Developers with private or off-GitHub work who still want to showcase selected projects in a portfolio without making the code public, since PRG can list private repositories (the code stays inaccessible) and non-GitHub projects.
- Developers who want to avoid creating multiple GitHub accounts or organizations to separate high-quality work from smaller experiments.
What can you do with PRG?
- Portfolio builders: categorize repositories into five tiers using PRG.md files and let GitHub Actions generate a public portfolio page hosted on GitHub Pages.
- Open-source maintainers: apply the provided README templates and repository structure guidelines to standardize new projects from the start.
- GitHub profile enhancers: add the PRG Collection badge to your profile README, linking visitors to your categorized project tier table.
- Project curators: hide specific repositories from the table entirely by configuring flags in the generator script, so you control exactly what the public sees.
How does PRG work?
- Fork the PRG-Personal-Repository-Guidelines repository.
- Edit the script
scripts/project_tier_table_generator.py and set the TIER_TABLE_URL variable to your site URL.
- Place a PRG.md file in the root of each repository you want to categorize, specifying its tier and metadata.
- Create a repository logo named
PRG.png in each repo's docs/images folder if you want logos in the table.
- Add the matching tier badge to the top of each repository's README.
- Enable GitHub Actions and configure GitHub Pages deployment, then optionally add the PRG Collection badge to your profile README.
FAQ
How do I determine the tier of my repository?
The repository provides a Category Guidelines document (guidelines/category_guidelines.md) that explains what each tier means and how to assign one based on project quality and maturity. It also covers naming conventions and badge usage.
Can I exclude a repository from my PRG portfolio?
Yes. If a repository has no PRG.md file, it is simply not brought into your portfolio. You can also configure flags in the tier table generator script to exclude specific repositories from the generated table, as described in the Table Generator Guide.
What does "Optimized" mean?
In PRG, "Optimized" means a repository that is categorized and included in the PRG framework, but not assigned a specific Platinum, Gold, Silver, or Bronze tier. It serves as a default for projects that use PRG without a tier badge.
What kinds of repositories can I include?
You can include any repository, project, or product — open source or closed source, private GitHub repositories (the code remains inaccessible), and even projects published outside GitHub. PRG is primarily tailored for GitHub but the guidelines can be adapted to other version control systems.
Is PRG free to use?
Yes. The PRG repository is available on GitHub under an open license (the README includes a LICENSE file and a CITATION.cff). Setup requires only a GitHub account, GitHub Actions, and GitHub Pages, which are included in GitHub's free tier for public repositories.
