CI for all three forges: build README.html and publish as artifact

.forgejo/workflows/build-readme.yml

@@ -0,0 +1,30 @@
+name: Build README.html
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container:
+      image: pandoc/core:3.1
+
+    steps:
+      - name: Checkout
+        # Forgejo documents that actions/checkout can be referenced via DEFAULT_ACTIONS_URL,
+        # or explicitly via a Forgejo-hosted URL.
+        uses: actions/checkout@v4
+        # Alternatively:
+        # uses: https://data.forgejo.org/actions/checkout@v4
+
+      - name: Build README.html
+        run: ./scripts/build_readme.sh
+
+      - name: Upload artifact
+        # Forgejo docs recommend v3 (or patched v4).
+        uses: https://code.forgejo.org/actions/upload-artifact@v3
+        with:
+          name: README-html
+          path: README.html

.gitea/workflows/build-readme.yml

@@ -0,0 +1,26 @@
+name: Build README.html
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container:
+      image: pandoc/core:3.1
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build README.html
+        run: ./scripts/build_readme.sh
+
+      # If Gitea instance can fetch GitHub actions:
+      - name: Upload artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: README-html
+          path: README.html

.gitlab-ci.yml

@@ -0,0 +1,15 @@
+stages: [build]
+
+build_readme_html:
+  stage: build
+  image: pandoc/core:3.1
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "push"
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  script:
+    - ./scripts/build_readme.sh
+  artifacts:
+    name: "readme-html-$CI_COMMIT_SHORT_SHA"
+    paths:
+      - README.html
+    expire_in: 30 days

README.md

@@ -1,5 +1,24 @@
 # Internal Forge Comparison
 
+This repository lists the pros and cons of three popular open-source Git forges (**GitLab CE**, **Gitea**, and **Forgejo**) based on a side-by-side comparison in a self-hosted test lab on a single VPS ([github.com/matteodelucchi/gitforgelab](https://github.com/matteodelucchi/gitforgelab)).
+The goal is to provide a practical reference for teams and organizations evaluating which Git forge best fits their needs, based on real-world usage and feature comparisons.
+
+## Why This Exists
+Choosing the right Git forge for a team or company is not trivial. 
+Each platform differs in resource usage, feature set, administration complexity, and SSO integration. 
+This lab deploys all three behind a shared reverse proxy with centralised OIDC authentication so they can be evaluated under identical conditions (same hardware, same identity provider, same workflow).
+
+The entire infrastructure is defined as code (Terraform + Ansible + Docker Compose) and can be torn down and recreated in minutes.
+
+## Limitations
+This is a **test lab**, not a production deployment.
+- Runs on a **single VPS**. There is no high-availability, redundancy, or horizontal scaling.
+- **SSH Git access is disabled**; repositories are accessed over HTTPS only.
+- All services share **one PostgreSQL and one Redis** instance to save resources.
+- GitLab is **memory-tuned aggressively** (2 Puma workers, 5 Sidekiq concurrency) and will be slow under real workloads.
+- No backup strategy is included.
+
+# Comparison
 ## Quick decision guide
 
 | If we want…                                                                                                                | Choose      |
@@ -8,7 +27,8 @@
 | A **lightweight, easy-to-operate Git server** with minimal resource usage                                                  | **Gitea**   |
 | A **community-driven forge** similar to Gitea but with **built-in CI (Forgejo Actions)** and future **federation support** | **Forgejo** |
 
-# Comparison
+A more detailed comparison that covers forgejo specific features and limitations is available in the [forgejo.org/compare](https://forgejo.org/compare/).
+
 ## Pricing
 | Feature                                   | GitLab | Gitea | Forgejo |
 |-------------------------------------------|:------------------:|:-----------------:|:-------------------:|

scripts/build_readme.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+in="README.md"
+out="README.html"
+
+if [[ ! -f "$in" ]]; then
+  echo "ERROR: $in not found" >&2
+  exit 1
+fi
+
+# GitHub-flavored Markdown -> standalone HTML
+pandoc "$in" \
+  --from=gfm \
+  --to=html5 \
+  --standalone \
+  --metadata title="README" \
+  --output "$out"
+
+echo "Built $out"