GO — Healthy across all four use cases

• Last commit 8mo ago
• 40+ active contributors
• MIT licensed
• CI configured
• ⚠ Slowing — last commit 8mo ago
• ⚠ Concentrated ownership — top contributor handles 58% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

A curated, community-maintained list of open-source startup alternatives to commercial SaaS products, with data stored as YAML files in /submissions/ and automatically synced to a Docusaurus-powered website. It bridges discoverers looking for open-source options (like Airbyte, Cal.com, Appwrite) with their SaaS equivalents (data pipelines, scheduling, backends), powered by Python build scripts that parse YAML and generate both a README.md and static HTML. Monorepo structure: /submissions/ contains 100+ YAML files (one per OSS company), Python scripts in root (build_readme.py, build_website.py, sort.py) orchestrate data transforms, /docs/ (inferred from Docusaurus config) holds static content, and GitHub Actions in .github/workflows/ auto-generate README.md and trigger website rebuilds on submissions changes.

Open-source enthusiasts and startup founders evaluating whether to adopt open-source alternatives to paid tools, plus contributors who submit new projects. Developers at open-source companies use it for visibility; SaaS evaluators use it for comparisons.

Actively maintained: 60+ YAML submissions across diverse categories, multiple automated GitHub Actions workflows for syncing and deployment, and Docusaurus 2.0 beta for the website indicate serious infrastructure. However, the use of 2.0.0-beta.22 Docusaurus (not stable) and the presence of .history/ files suggest ongoing evolution. Verdict: actively developed with production-ready content, though the framework choice is pre-stable.

Minimal code risk but organizational risk: Python build scripts (build_readme.py, build_website.py, create_yamls.py) have no visible tests, making refactors fragile. Four concurrent GitHub Actions workflows (direct_merge, merge_created, push_to_readme, push_to_yaml) suggest potential race conditions or redundant logic. Heavy reliance on YAML-to-markdown/website generation means a single schema change could break many downstream outputs.

Continuous growth: submissions are being merged, likely via pull requests that trigger the four CI workflows. The direct_merge_to_readme.yaml and push_to_yaml.yaml suggest automated syncing between YAML sources and the rendered README. The Docusaurus deployment workflow indicates the website is actively published.

git clone https://github.com/RunaCapital/awesome-oss-alternatives.git
cd awesome-oss-alternatives
npm install
npm start

This starts the Docusaurus dev server on http://localhost:3000/.

Daily commands:

npm start          # Docusaurus dev server on :3000
npm run build      # Build static HTML to /build/
npm run serve      # Serve built site locally
python build_readme.py   # Regenerate README.md from submissions/
python build_website.py  # Regenerate website content

• README.md — Primary entry point and source-of-truth documentation listing all OSS alternatives with categories and links; basis for all generated outputs.
• build_readme.py — Core Python script that converts YAML submissions into README.md format; orchestrates the data pipeline.
• submissions — Directory containing 100+ YAML files (each OSS project) that serve as the structured data source for the entire project.
• build_website.py — Generates Docusaurus-compatible website content from submission data; powers the web frontend.
• docusaurus.config.js — Main Docusaurus configuration file that defines site metadata, navigation, and build settings.
• .github/workflows — GitHub Actions workflows that automate README generation, YAML validation, and deployment on every push/PR.
• .github/CONTRIBUTING.md — Contributor guidelines explaining submission format, YAML structure, and review process for new OSS alternatives.

• Submission YAML Files (submissions/*.yaml) (YAML) — Structured data source containing project metadata (name, repo, homepage, description, SaaS alternatives, license, pricing, etc.)
  • Failure mode: Invalid YAML syntax or missing required fields cause build_readme.py to fail; CI workflow catches this and blocks merge
• Build Scripts (build_readme.py, build_website.py) (Python 3, PyYAML) — Transform YAML data into README.md and Docusaurus site; apply sorting, validation, and formatting rules
  • Failure mode: Script errors or logic bugs produce malformed output; website renders incorrectly or README shows duplicate/missing entries
• README.md (Markdown) — Primary human-readable index of all OSS alternatives; serves as landing page and canonical source of truth
  • Failure mode: Build script produces corrupted README; users see stale or incorrect data; must regenerate via script
• Docusaurus Site (Docusaurus 2.0, React, Prism, MDX) — Static website with search, sidebar navigation, and responsive design; deployed to GitHub Pages
  • Failure mode: Build fails due to invalid markdown or config; site does not deploy; users cannot access web version
• GitHub Actions Workflows (GitHub Actions YAML) — Automated validation, build, and deployment on every push/PR; enforces data quality and updates website
  • Failure mode: Workflow misconfiguration prevents automatic deployment; contributor changes are not published; site falls out of sync

• Contributor submits PR → submissions/*.yaml file — New or updated OSS project metadata committed to repo
• GitHub Actions (push_to_yaml.yaml) → YAML validation — Workflow triggers on file change; validates schema and format of submissions
• GitHub Actions (push_to_readme.yaml) → build_readme.py — Workflow invokes Python script to parse all YAMLs and regenerate README.md
• build_readme.py → README.md — Script generates markdown file with projects organized by category, sorted alphabetically
• GitHub Actions (deploy.yml) → build_website.py — Workflow invokes build script to convert submissions to Docusaurus markdown and trigger site build
• `` → undefined — undefined

Add a new OSS project to the awesome list

1. Create a new YAML file in submissions/ directory (e.g., submissions/MyProject.yaml) following the schema defined in .github/CONTRIBUTING.md with name, homepage, repo, description, and SaaS alternatives (submissions/)
2. Run build_readme.py to parse the new YAML and auto-generate README.md with your project in the appropriate category (build_readme.py)
3. Run build_website.py to update Docusaurus website content with the new entry (build_website.py)
4. Push changes; GitHub Actions workflows automatically validate YAML format, update README, and redeploy the website (.github/workflows/)

Reorganize categories or update display format

1. Edit build_readme.py to modify how submissions are grouped, sorted, or formatted in the README output (build_readme.py)
2. Edit build_website.py to reflect the same category/format changes in the Docusaurus site (build_website.py)
3. Test locally by running the build scripts and checking the generated README.md and website output (README.md)
4. Commit and push; workflows will redeploy the website with new layout (.github/workflows/)

Maintain data quality and add validation rules

1. Update .github/CONTRIBUTING.md to document new required YAML fields or validation constraints (.github/CONTRIBUTING.md)
2. Add validation logic to build_readme.py and build_website.py to enforce the new schema rules (build_readme.py)
3. GitHub Actions workflows (push_to_yaml.yaml) will now reject submissions that don't comply with updated schema (.github/workflows/push_to_yaml.yaml)

• Python (build scripts) — Simple, portable, and excellent for file I/O and YAML parsing; no runtime server needed for a static content generator
• YAML format for submissions — Human-readable, version-control-friendly, and easy for community contributions; avoids database complexity
• Docusaurus 2.0 — Modern static site generator with built-in search, responsive design, and low hosting costs (GitHub Pages compatible)
• GitHub Actions — Native CI/CD with no external dependencies; automatically triggers on push/PR for rapid feedback and automated deployments
• Markdown for content — Universal, Git-friendly, and renders natively on GitHub; easy to review and maintain

• Static generation (YAML → README → HTML) rather than database-backed dynamic site

  • Why: Simplicity, version control, offline-first, and low operational overhead
  • Consequence: Cannot serve real-time updates or personalized queries; regeneration required for any data change

• Crowdsourced YAML submissions instead of curated internal database

  • Why: Community-driven scaling and transparency; leverages open-source culture
  • Consequence: Requires validation workflows to maintain data quality; potential inconsistencies in submission format

• Docusaurus over custom React/Next.js site

  • Why: Reduces development burden; built-in SEO, search, and versioning
  • Consequence: Less fine-grained control over UX; tied to Docusaurus update cycle

• Does not provide a public API for querying OSS alternatives programmatically
• Does not track real-time metrics or popularity scores (GitHub stars, download counts)
• Does not handle user authentication or account management
• Does not support interactive filtering/search beyond client-side browser search
• Does not automatically sync or validate external project data (assumes humans maintain submissions)

No hidden env vars or service dependencies visible, but critical gotcha: the four GitHub Actions workflows (direct_merge_to_readme, merge_created_new_yaml, push_to_readme, push_to_yaml) may race or conflict if multiple PRs merge simultaneously—clarify which workflow is canonical. Docusaurus beta risk: upgrading to stable 2.x may require breaking changes. Python script fragility: no tests or type hints visible; YAML schema changes will silently break downstream builds unless manually re-run.

• sindresorhus/awesome — The original 'awesome' list framework that this repo follows; understanding the awesome-list format and philosophy is foundational
• getlago/lago — An open-source SaaS alternative (billing/metering platform) that would likely be a candidate for inclusion in this list
• docusaurus/docusaurus — The static site generator powering the website; understanding Docusaurus is essential for modifying site structure and deployment
• supabase/supabase — Flagship open-source Firebase alternative likely already in the submissions; exemplifies the category this repo curates
• RunaCapital/ROSS-index — Sister project (mentioned in README) tracking the fastest-growing open-source startups quarterly; likely shares methodology and governance

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add YAML schema validation workflow for submissions/

The repo has 100+ YAML files in submissions/ but no CI validation to ensure consistency. This prevents malformed entries from being merged. Currently, there are Python scripts (create_yamls.py, build_readme.py) that depend on YAML structure, but no automated checks. A GitHub Action using a JSON schema or yamllint + custom validator would catch missing fields (name, description, alternatives, etc.) before merge.

• [ ] Create .github/workflows/validate-yaml.yaml to run on PRs modifying submissions/*.yaml
• [ ] Define YAML schema in a new docs/ or config/ directory (e.g., submission-schema.json)
• [ ] Add validation step using yamllint and jsonschema Python library against sample submissions/
• [ ] Update .github/CONTRIBUTING.md to document the required YAML structure and link to schema

Add Python unit tests for build scripts (build_readme.py, build_website.py, create_yamls.py)

The repo has critical Python scripts that parse YAML and generate the README and website, but zero test coverage. There's no tests/ directory. This is risky for refactoring and new contributions. Mock YAML files in submissions/ and test that build_readme.py correctly parses, sorts, and formats output.

• [ ] Create tests/ directory with init.py
• [ ] Create tests/test_build_readme.py with fixtures for valid/invalid YAML submissions
• [ ] Create tests/test_create_yamls.py to validate YAML generation logic
• [ ] Add pytest to dev dependencies in package.json and create GitHub Action workflow (.github/workflows/test-python.yaml) to run on PRs

Add validation for duplicate SaaS product entries across submissions/

With 100+ submissions, there's high risk of duplicate entries for the same SaaS alternative (e.g., two separate YAML files for the same tool with slightly different names). Currently no tooling prevents this. A Python script + GitHub Action could detect near-duplicates by checking the 'alternatives' field and fuzzy matching, preventing confusing duplication in the final README.

• [ ] Create scripts/check_duplicates.py that parses all submissions/*.yaml and flags products appearing in multiple files or similar names (using difflib)
• [ ] Add this check to .github/workflows/validate-yaml.yaml as a separate step that fails the build if duplicates found
• [ ] Output a clear error message in PR showing conflicting files (e.g., 'Appwrite.yaml and Appwrite_Backend.yaml both list Firebase as alternative')
• [ ] Document in .github/CONTRIBUTING.md how to avoid duplicates and what naming conventions to follow

• Add unit tests to build_readme.py and build_website.py: currently zero test coverage means refactors risk breaking the README/website generation pipeline.
• Document the four GitHub Actions workflows (direct_merge, merge_created, push_to_readme, push_to_yaml) in .github/CONTRIBUTING.md: clarify which fires when and why we need four, or consolidate to reduce race conditions.
• Add a YAML schema validator (e.g., with jsonschema or pydantic) to validate /submissions/*.yaml before they're merged, preventing malformed entries from breaking the build.

This is a static documentation site with a relatively good security posture for its purpose. The main concerns are outdated dependencies (Docusaurus beta and React 17) that should be upgraded to stable versions. The presence of .history files in version control is a hygiene issue rather than a critical security risk. The project lacks a formal security policy. No injection vulnerabilities, hardcoded secrets, or misconfigurations were detected in the visible codebase structure. Given the nature of the project (an awesome list / documentation), the security risk is primarily dependency-related rather than architectural.

• High · Outdated Docusaurus Beta Version — package.json - @docusaurus/core and @docusaurus/preset-classic. The project uses Docusaurus 2.0.0-beta.22, which is a beta release from 2021-2022. Beta versions lack the security patches and stability guarantees of stable releases. This could expose the application to known vulnerabilities that have been fixed in later stable versions. Fix: Upgrade to the latest stable version of Docusaurus (3.x or later). Run 'npm update @docusaurus/core @docusaurus/preset-classic' and test thoroughly.
• Medium · Outdated React Version — package.json - react and react-dom dependencies. React 17.0.2 is being used. While not critically outdated, React 18.x+ includes security improvements and performance enhancements. The gap may expose the application to vulnerabilities fixed in newer versions. Fix: Upgrade to React 18.x LTS or later. Review breaking changes and update components accordingly before deploying.
• Medium · Undocumented .history Directory — .history/ directory. The .history directory contains multiple timestamped versions of README.md files. This appears to be editor backup/version history (likely from VS Code). While not a direct security threat, it represents unnecessary bloat and could potentially expose sensitive information if committed to the repository. Fix: Add .history/ to .gitignore and remove the directory from version control using 'git rm -r --cached .history/'. This is typically auto-generated and should not be committed.
• Low · No Security Policy Defined — Repository root. There is no SECURITY.md file visible in the repository structure. This makes it unclear how security vulnerabilities should be reported responsibly. Fix: Create a SECURITY.md file outlining responsible disclosure procedures for security vulnerabilities.
• Low · Missing npm Audit Review — package.json and CI/CD workflows. No evidence of regular npm audit runs or security monitoring documented. Dependencies may have known vulnerabilities that should be regularly scanned. Fix: Add 'npm audit' to CI/CD pipeline (.github/workflows/). Consider using Dependabot for automated dependency updates.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/RunaCapital/awesome-oss-alternatives shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live RunaCapital/awesome-oss-alternatives repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/RunaCapital/awesome-oss-alternatives.

What it runs against: a local clone of RunaCapital/awesome-oss-alternatives — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in RunaCapital/awesome-oss-alternatives | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 278 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of RunaCapital/awesome-oss-alternatives. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/RunaCapital/awesome-oss-alternatives.git
#   cd awesome-oss-alternatives
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of RunaCapital/awesome-oss-alternatives and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "RunaCapital/awesome-oss-alternatives(\\.git)?\\b" \\
  && ok "origin remote is RunaCapital/awesome-oss-alternatives" \\
  || miss "origin remote is not RunaCapital/awesome-oss-alternatives (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "build_readme.py" \\
  && ok "build_readme.py" \\
  || miss "missing critical file: build_readme.py"
test -f "submissions" \\
  && ok "submissions" \\
  || miss "missing critical file: submissions"
test -f "build_website.py" \\
  && ok "build_website.py" \\
  || miss "missing critical file: build_website.py"
test -f "docusaurus.config.js" \\
  && ok "docusaurus.config.js" \\
  || miss "missing critical file: docusaurus.config.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 278 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~248d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/RunaCapital/awesome-oss-alternatives"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.