{"id":51440455,"url":"https://github.com/louis-fiori/forgepath","last_synced_at":"2026-07-05T11:01:06.759Z","repository":{"id":367321253,"uuid":"1277954606","full_name":"louis-fiori/forgepath","owner":"louis-fiori","description":"An open-source starter kit for an AI-ready Internal Developer Platform, local-first, GitOps-driven, observable by default.","archived":false,"fork":false,"pushed_at":"2026-06-25T12:49:46.000Z","size":5267,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T14:21:04.682Z","etag":null,"topics":["ai-tools","devops","gitops","kubernetes","observability","platform-engineering"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/louis-fiori.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-23T10:33:05.000Z","updated_at":"2026-06-25T12:49:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/louis-fiori/forgepath","commit_stats":null,"previous_names":["louis-fiori/forgepath"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/louis-fiori/forgepath","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/louis-fiori%2Fforgepath","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/louis-fiori%2Fforgepath/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/louis-fiori%2Fforgepath/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/louis-fiori%2Fforgepath/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/louis-fiori","download_url":"https://codeload.github.com/louis-fiori/forgepath/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/louis-fiori%2Fforgepath/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35151638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","devops","gitops","kubernetes","observability","platform-engineering"],"created_at":"2026-07-05T11:01:05.881Z","updated_at":"2026-07-05T11:01:06.754Z","avatar_url":"https://github.com/louis-fiori.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ForgePath ⚒️\n\n**An open-source starter kit for an AI-ready Internal Developer Platform, local-first, GitOps-driven, observable by default.**\n\nForgePath shows how a small platform team can give application developers a clean self-service experience: open a PR from Backstage, see your service running in a preview namespace seconds later, close the PR to tear it down. Cluster state stays fully described in Git; ArgoCD reconciles; Prometheus and Loki give you metrics and logs without per-service wiring. An AI Incident Analyzer watches the same observability stack, asks Claude to diagnose what broke, and surfaces the result as a GitHub issue and a Backstage notification.\n\n\u003e 🚧 **Status:** Work in progress\n\u003e 🎯 **Scope:** Reference implementation / portfolio project / learning-oriented starter kit\n\u003e ⚠️ **Not production-ready**, emptyDir storage, demo-grade limits, no HA, no real auth.\n\n---\n\n## ✨ What it does\n\n- **Self-service deploys**, fill a Backstage form, get a PR with rendered K8s manifests\n- **Auto preview environments**, labeled PRs are deployed into `preview-scaffold-\u003cname\u003e` namespaces by ArgoCD\n- **Observability by default**, Prometheus scrapes every pod for CPU/memory, Promtail forwards every log line into Loki, three Grafana dashboards (`Cluster pods` + `Service logs` + `Logs · Error explorer`) are auto-provisioned and deep-linked from each service's catalog entry\n- **TechDocs runbooks**, each scaffolded service ships with an editable mkdocs runbook, served straight in Backstage\n- **AI incident detection**, the `incident-analyzer` watches Loki, Prometheus and the K8s API; on an error spike / OOMKill / CrashLoop it asks Claude (via Bedrock or the direct Anthropic API) for a root cause + remediation, then files a GitHub issue and a Backstage notification. Sensitive data is masked before it ever reaches the LLM. Run it on a poll loop or on demand from a Backstage form.\n- **Closing the PR cleans up**, ArgoCD ApplicationSet prunes the namespace, Backstage marks the catalog entity orphan once the branch is gone\n\n---\n\n## 🚀 Quickstart\n\n```bash\ngit clone https://github.com/louis-fiori/forgepath.git \u0026\u0026 cd forgepath\ncp .env.example .env  # fill in GITHUB_TOKEN (fine-grained PAT, see .env.example)\n\nmake deps             # install prerequisites (Docker, kind, kubectl, Node 22, Yarn) — or `make doctor` to just check\nmake backstage-init   # scaffolds local/backstage/ (~5 min, one-time)\nmake backstage-build  # builds the Backstage Docker image (~5 min, one-time)\nmake local-up         # creates the kind cluster + applies the platform\n```\n\n\u003e Works on macOS, Linux, and Windows via WSL2. `make deps` auto-detects your package manager (Homebrew / apt / dnf / pacman / zypper); `make doctor` reports what's missing without installing anything.\n\nAfter `make local-up`:\n\n| Service        | URL                       | Credentials                          |\n|----------------|---------------------------|--------------------------------------|\n| Backstage      | http://localhost:7007     | guest auth                           |\n| ArgoCD UI      | http://localhost:8080     | admin / `make argocd-pw`             |\n| Grafana        | http://localhost:3000     | admin / `make grafana-pw`            |\n| Preview demo slot | http://localhost:8888  | n/a (any preview with `exposeOnLocalhost: true`) |\n| incident-generator | http://localhost:8889  | n/a (`make incident TYPE=panic` to trigger one) |\n\nFull walkthrough, including prerequisites and platform-specific notes, in [docs/quickstart.md](docs/quickstart.md).\n\n---\n\n## 💻 Platform support \u0026 prerequisites\n\nForgePath runs on **macOS**, **Linux**, and **Windows (via WSL2)**. The whole flow is `make` + bash scripts, so `make deps` installs the prerequisites for you and `make doctor` just checks them, on every platform.\n\n### Prerequisites\n\n| Tool     | Min version | Why it's needed                         |\n|----------|-------------|-----------------------------------------|\n| Docker   | recent      | Runs the kind node and builds the images |\n| kind     | 0.20+       | Local single-node Kubernetes cluster     |\n| kubectl  | 1.28+       | Talks to the cluster                     |\n| Node     | 22+         | Builds the Backstage app (via nvm)       |\n| Yarn     | 1.x+        | Backstage scaffolder and build           |\n| GNU make | 3.81+       | Task runner for every entrypoint         |\n| openssl  | recent      | Generates the Grafana admin password     |\n\nYou don't need to install these by hand:\n\n```bash\nmake doctor   # report what's installed / missing / outdated (changes nothing)\nmake deps     # install the gaps via the detected package manager (idempotent)\n```\n\n`make deps` auto-detects your package manager (**Homebrew**, **apt**, **dnf/yum**, **pacman**, **zypper**), installs Node through [nvm](https://github.com/nvm-sh/nvm), and fetches `kind`/`kubectl` as pinned binaries where no package exists. Then pick your OS below and run the [Quickstart](#-quickstart) commands.\n\n### 🍎 macOS (Apple Silicon + Intel)\n\nNeeds [Homebrew](https://brew.sh) and [Docker Desktop](https://www.docker.com/products/docker-desktop/). `make deps` pulls kind, kubectl, Node (nvm), Yarn, openssl, and the Docker Desktop cask via Homebrew. **Launch Docker Desktop once** so the engine is running, then run the Quickstart.\n\n### 🐧 Linux\n\nDebian/Ubuntu (apt), Fedora/RHEL (dnf/yum), Arch (pacman), and openSUSE (zypper) are all detected. In addition to the CLIs, `make deps` installs the Docker engine, adds you to the `docker` group, and enables the service:\n\n```bash\nmake deps\nnewgrp docker          # or log out/in, so docker works without sudo\n```\n\nThen run the Quickstart.\n\n### 🪟 Windows (WSL2)\n\nNative Windows shells (PowerShell, cmd) are **not** supported. Use **WSL2** with Docker Desktop's WSL backend, every command then runs unchanged inside the WSL shell:\n\n1. Install [WSL2](https://learn.microsoft.com/windows/wsl/install) and a Linux distro (e.g. Ubuntu).\n2. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) and enable **Settings → Resources → WSL integration** for your distro.\n3. Clone the repo **inside the WSL filesystem** (e.g. `~/forgepath`, not `/mnt/c/...`) for usable file I/O.\n4. From the WSL shell, run `make deps` then the Quickstart.\n\n\u003e On WSL2, `make deps` installs the CLIs via apt but **deliberately skips the Docker engine** — Docker Desktop provides it through the WSL integration (there's no systemd to run a local daemon).\n\n---\n\n## 🧩 What's in the box\n\n| Component            | Role                                                 | Where it lives                      |\n|----------------------|------------------------------------------------------|-------------------------------------|\n| **Backstage**        | Developer portal, catalog, scaffolder, Kubernetes UI | `platform/backstage/`               |\n| **ArgoCD**          | GitOps engine, syncs `gitops/` to the cluster        | `platform/argocd/`, `gitops/platform/`  |\n| **Prometheus**       | Pod metrics via kubelet/cAdvisor + annotation-based scraping | `gitops/platform/prometheus/`       |\n| **Loki + Promtail**  | Cluster-wide log ingestion (every pod, no wiring)    | `gitops/platform/loki/`             |\n| **Grafana**          | Dashboards + datasources, auto-provisioned           | `gitops/platform/grafana/`          |\n| **incident-analyzer**| AI incident detector, Loki/Prometheus/K8s → Claude → GitHub issue + Backstage notification | `services/incident-analyzer/`       |\n| **incident-generator**| Chaos fixture that misbehaves on purpose so there's something to detect | `services/incident-generator/`      |\n| **kind cluster**     | Local single-node K8s with port mappings             | `local/kind-config.yaml`            |\n\nThe architecture, GitOps flow, and observability wiring are described in [docs/architecture.md](docs/architecture.md). Working IN the repo (make targets, customizations, fork setup) is covered in [docs/development.md](docs/development.md).\n\nOnce the cluster is up, Backstage also serves the in-product **TechDocs** version of the operations guide at \u003chttp://localhost:7007/docs/default/component/forgepath-platform\u003e.\n\n---\n\n## 🚫 What it isn't\n\n- A production-ready platform (no HA, no PVCs, no real auth, no rate limiting)\n- A complete AIOps tool, the AI Incident Analyzer detects and diagnoses, but it isn't a full alerting/correlation pipeline\n- An autonomous remediation agent, the analyzer files an issue and notifies; humans drive every change\n- A clone of Backstage, ArgoCD, Datadog, or any existing platform\n- A universal framework for every Kubernetes use case\n\nIt is a practical starter kit meant to be read, tested, adapted, and extended.\n\n---\n\n## 🚧 Production gaps\n\n**ForgePath is a learning project, not a production platform.** The shortcuts below are deliberate, they keep the repo small, local-first, and readable. Each is a conscious trade-off, not an oversight. If you wanted to take this to production, this is the list you'd have to work through:\n\n| Area | What ForgePath does | What production would need |\n|---|---|---|\n| **Storage** | `emptyDir` everywhere, Loki, Grafana, Prometheus lose all data on pod restart | PersistentVolumeClaims (or managed log/metric backends), backups, retention policy |\n| **Availability** | Single-node kind, one replica per component, no PodDisruptionBudgets | Multi-node, HA control plane, replicas + anti-affinity, autoscaling |\n| **AuthN / AuthZ** | Backstage guest auth, `allow-all` permission policy, ArgoCD `server.insecure=true` | Real SSO/OIDC, RBAC and Backstage permission policies, TLS everywhere |\n| **Secrets** | Materialized into K8s Secrets from `.env` + `~/.aws` at boot | A secrets manager (Vault / External Secrets / cloud KMS), rotation, no plaintext on disk |\n| **Images** | Built locally and side-loaded into kind, tagged `:dev` | A registry, immutable digests, image signing + provenance, vulnerability scanning |\n| **Analyzer state** | In-memory dedup cache, lost on restart, so an incident can re-file after a redeploy | Durable dedup (DB/CRD), correlation across incidents, alert suppression windows |\n| **Networking** | No NetworkPolicies, no ingress controller, NodePort + host port-maps | Ingress/Gateway, NetworkPolicies, mTLS / service mesh as needed |\n| **Tenancy** | Single trust domain, no resource quotas on preview namespaces | Namespace quotas/limits, multi-tenancy isolation, cost controls |\n| **Supply chain** | CI lints + tests the services, validates manifests, and Trivy-scans both service images for CRITICAL/HIGH CVEs; no SBOM or signing | SBOMs, signed releases, provenance, policy gates |\n\nSee [docs/architecture.md](docs/architecture.md) for the intentional boundaries behind these choices, [SECURITY.md](SECURITY.md) for the security policy (secrets, LLM data, reporting, pre-exposure checklist), and [docs/threat-model.md](docs/threat-model.md) for the threat-by-threat breakdown.\n\n---\n\n## 📄 License\n\nForgePath is released under the [Apache License 2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flouis-fiori%2Fforgepath","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flouis-fiori%2Fforgepath","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flouis-fiori%2Fforgepath/lists"}