Forgejo Introduction - Forgejo as a GitHub Alternative

Status: Active
Last Updated: 2026-08-14
Category: CI/CD - Phase 2: Forgejo (Self-Hosted Git)
Prerequisites: Git basics, self-hosted-vs-cloud
Time: 1 hour
Tags: forgejo, gitea, self-hosted-git, git-forge, overview

Summary

Forgejo is a community-governed, lightweight, self-hosted Git forge — the "GitHub experience" running on hardware you control in roughly 500MB of RAM. This article explains what Forgejo is, where it came from (the Gitea fork), why it beats Gitea and GitLab for many self-hosters, and which use cases it fits best.

🎯 What You'll Learn

By the end of this article, you'll be able to:

✅ Explain what Forgejo is and its relationship to Gitea
✅ Argue why Forgejo over Gitea or GitLab for a homelab/small team
✅ Map GitHub concepts onto their Forgejo equivalents
✅ Identify the use cases where Forgejo shines — and where it doesn't

What Is Forgejo?

Forgejo (pronounced /forˈd͡ʒe.jo/, "forge" in Esperanto) is a self-hosted software forge: Git repository hosting plus issues, pull requests, wiki, releases, organizations, and webhooks — everything you use GitHub for, served from your own machine.

The technical profile:

Language:        Go (single static binary)
License:         MIT + GPL v3 components — fully open source
Resources:       ~512MB RAM minimum, comfortable at 1GB
Storage:         Plain Git repositories on disk (nothing exotic)
Database:        SQLite (default), PostgreSQL, or MySQL/MariaDB
Integrations:    Webhooks, OAuth2 provider + consumer, container registry,
                 Actions-compatible CI runner, ActivityPub (federation)

What Happens under the hood: every repo is an ordinary bare Git directory on disk. You can git clone over HTTP or SSH; backups are literally file copies plus the database. There is no proprietary data format holding your history hostage.

The Backstory: The Gitea Fork

Understanding Forgejo requires one paragraph of history:

2014  Gogs — lightweight self-hosted Git service appears
2016  Gitea — community hard-fork of Gogs after stalled maintenance
2022  Gitea Ltd. (the company) is formed; trademark moves to a for-profit
      entity; cloud offering planned. Community worries about repeat of
      earlier open-core drift patterns seen elsewhere.
Oct 2022  Codeberg e.V. (the nonprofit behind codeberg.org) launches
      FORGEJO as a community fork of Gitea — governance placed under
      nonprofit democratic control from day one.
2023+  Forgejo gains its own runner (Actions-compatible), federation
      work, and ships independently while remaining largely compatible
      with Gitea's API and data model.

The fork wasn't about code quality — Gitea was fine. It was about who controls the project. Forgejo's answer: a nonprofit (Codeberg e.V.) with a general assembly, so no single company can relicense or de-open features.

Why Forgejo Over the Alternatives

vs Gitea

Dimension	Forgejo	Gitea
Governance	Nonprofit (Codeberg e.V.), open decision process	Gitea Ltd. (company-controlled trademark)
License risk	Hard commitment to free licensing	Same MIT today; governance is the differentiator
Built-in Actions runner	Ships its own (`forgejo-runner`)	Relies on external `act_runner`
Federation (ActivityPub)	Active development priority	Not prioritized
Compatibility	API/data compatible with Gitea today	—

Practically: they're near-twins today. Choose Forgejo if governance and long-term openness matter to you (they compound over years); choose Gitea if you have an existing investment there — migration between them is nearly trivial.

vs GitLab

Dimension	Forgejo	GitLab CE
RAM footprint	0.5–1GB	8GB+ recommended
Install complexity	Single container	Omnibus bundle: nginx, redis, postgres, sidekiq, gunicorn…
Upgrade path	Bump image tag	Follow versioned upgrade rails, sometimes stepwise
Features	Focused core done well	Huge suite (CI built-in, pages, registry, scanning, epics…)
Open-core boundary	None — all MIT/GPL	Proprietary tiers above CE; features move up over time

Rule of thumb: if you need GitLab's enterprise suite, run GitLab (or SaaS). If you need "GitHub but mine," Forgejo gives you that at 10% of the operational cost.

vs GitHub SaaS

Covered fully in self-hosted-vs-cloud: privacy, jurisdiction, fixed costs, learning value vs. marketplace breadth and zero ops.

Feature Tour: GitHub Concepts → Forgejo Equivalents

You know it as (GitHub)	Forgejo calls it	Notes
Repository	Repository	Identical Git semantics; issues/PRs/wiki included
Organization	Organization (+ nested teams)	Team-based permission tiers
Pull Request	Pull Request	Also supports AGit workflow via `git push` options
Issue	Issue	Labels, milestones, assignments, dependencies
GitHub Actions workflows	Forgejo Actions (`.forgejo/workflows/` YAML)	Compatible subset; runs via `forgejo-runner`. This course pairs it with Woodpecker instead
Container registry (ghcr.io)	Built-in package/container registry	Per-repo, OCI-compliant
Releases	Releases	Attach binaries, auto-generated notes from tags
Pages	(via reverse proxy or Woodpecker artifact publishing)	No first-class Pages yet — plan accordingly
Social following	Limited user profiles	Federation aims to change this

Use Cases

Where Forgejo shines ✅

Homelab / personal infrastructure repos — your dotfiles, compose stacks, IaC, and KB live together on your LAN.
Small teams (2–50) wanting private hosting — orgs, teams, branch protection, and review workflows cover professional needs.
Client/NDA work — code never leaves your jurisdiction or hardware.
CI/CD learning labs — pairing Forgejo + Woodpecker (this course) teaches you how forges and runners actually talk.
Mirror/aggregation point — native mirroring pulls from GitHub/GitLab on schedule.

Where it's the wrong tool ❌

You need a public open-source community hub with discovery → GitHub's network effect wins
You need first-class GitHub Pages-style site hosting → assemble your own
You need monorepo-scale enterprise features (code owners at scale, advanced security dashboards) → GitLab/GitHub

Architecture Preview

Where Forgejo sits in the stack you'll build across this course:

                    ┌─────────────────────────────┐
   git push ───────►│  Forgejo     :3000/:22      │
                    │  - repos on disk            │
                    │  - users/orgs/webhooks ─────┼──► webhook event ─┐
                    └─────────────────────────────┘                   │
                                                                      ▼
                                       ┌────────────────────────────────────┐
                                       │  Woodpecker server  :8000          │
                                       │  - reads .woodpecker.yml           │
                                       │  - queues pipeline runs            │
                                       └───────────────┬────────────────────┘
                                                       ▼
                                       ┌────────────────────────────────────┐
                                       │  Woodpecker agent(s)               │
                                       │  - spawns build containers         │
                                       │  - pushes images to Harbor         │
                                       └────────────────────────────────────┘

Forgejo is the source of truth and the webhook emitter; Woodpecker is the muscle. Installation begins in the next article.

🛠️ Troubleshooting & Common Issues

Pre-install questions that cause post-install regret:

Question gone wrong	Consequence	Get it right
Choosing MySQL "because familiar"	Extra service to maintain for zero benefit at this scale	SQLite until you truly need Postgres (multi-instance/high load)
Skipping domain/reverse-proxy planning	Retrofitting HTTPS + SSH routing later means breaking remote URLs	Decide DNS + TLS strategy before install (next article)
Assuming Actions workflows port 1:1	Marketplace actions don't exist; pipelines fail	Prefer Woodpecker-native steps (this course's path)
Treating Forgejo like GitHub outage-wise	Surprise when your ISP/router reboots = "GitHub down"	Plan backups + monitoring like any infra (see monitoring-pipelines.md)

🔗 Related

Previous: self-hosted-vs-cloud
Next: forgejo-installation — Docker Compose deployment
Then: forgejo-organization, migrating-to-forgejo
Governance background: codeberg.org (Forgejo's flagship instance) and the Forgejo docs
Related KB: kb/gitops/gitops

Change Log

2026-08-14 — Initial version written as part of the KB course build-out (cicd directory).

Next Steps / Ops Actions

Run forgejo dump as the first post-install action and store the archive off-host immediately.
Configure the SMTP relay before any user accounts are created — password resets depend on it.
Set Forgejo Actions scope to enabled and protect main branches per branch-protection before enabling repos.
Plan the org/repo hierarchy now; reorganizing later breaks existing clone URLs and webhooks.