Forge

Jessie / forge public

Self-hosted git - made by qwen 3.8 27b

branch: main

Branches

main
History
Jessie Initial commit 0c9688e9 ·
forge Initial commit
forge.Tests Initial commit
.dockerignore Initial commit
.gitignore Initial commit
compose.yaml Initial commit
Dockerfile Initial commit
dotnet-tools.json Initial commit
forge.slnx Initial commit
README.md Initial commit

README.md

Forge

Forge is a self-hosted Git server with a web interface. It is built with ASP.NET Core (Blazor Server) and uses real bare Git repositories on disk, so any Git client can clone and push to it over HTTP(S).

Features

  • Repositories: create repos, browse files and folders, view blobs with syntax highlighting, and render Markdown previews.
  • History: commit list and commit details, branch and tag pages, compare any two refs, and a file-level diff view.
  • Pull requests: open, review and merge pull requests, with merge-conflict detection (git merge-tree) and branch protection rules.
  • Search: find repositories, file names and file contents.
  • Activity: weekly commit counts and contributors per repository.
  • Git over HTTP: clone and push with the smart HTTP protocol. Authentication uses personal access tokens (read-only or read/write).
  • Webhooks: signed deliveries for pushes and pull request events, with delivery status and retries.
  • Atom feeds: commit feeds for each repository.
  • Accounts: sign-up through a first-run setup page, login with rate limiting, and per-user repository access.
  • Languages: English and Slovak. The language is chosen in the footer and remembered in a cookie, with the browser's Accept-Language as the fallback.

Requirements

  • .NET SDK with the version targeted in forge/forge.csproj
  • Git 2.40 or newer (Forge uses git merge-tree --merge-base). Forge checks the version at startup and refuses to run with an older one.

Getting started

dotnet run --project forge

The default development profile listens on http://localhost:5207. On first run, open /setup to create the administrator account. Then create a repository at /new.

To clone a repository from Forge, use the URL shown on the repository page (<BaseUrl>/<owner>/<name>.git). Git asks for credentials: use your username, and a personal access token created at /settings/tokens as the password.

Configuration

Settings live in forge/appsettings.json under the Forge section. Any of them can be overridden with environment variables (for example Forge__BaseUrl) or with user secrets during development.

Setting Default Meaning
Forge:DataPath data Folder for forge.db and the repos/ directory. Relative paths resolve against the working directory.
Forge:BaseUrl http://localhost:5207 Public URL of the site. Used for clone URLs, feeds and webhook payloads. Must be an absolute http or https URL.
Forge:MaxPushSizeMb 500 Largest push Forge accepts, in megabytes.
Forge:GitPath git Git executable, a name on PATH or an absolute path.

Set BaseUrl to the address users actually visit. Using https:// also makes the session and CSRF cookies Secure.

Deploying with Docker

The Dockerfile builds an image with the app and git, running as a non-root user on port 8080, with all data in the /data volume. With Docker Compose:

  1. Set Forge__BaseUrl in compose.yaml to the public address of the server.
  2. Run docker compose up -d --build.
  3. Open /setup to create the administrator account.

compose.yaml publishes the port on 127.0.0.1 only, for a reverse proxy that terminates HTTPS. Forwarded headers (X-Forwarded-For, X-Forwarded-Proto) are honored, so rate limiting sees real client addresses. Allow request bodies as large as Forge:MaxPushSizeMb in the proxy (for nginx, client_max_body_size), and pass WebSocket upgrades through, which Blazor Server uses.

To update, pull the new code and run docker compose up -d --build again. Migrations run at startup.

Data and storage

  • forge.db is a SQLite database managed with Entity Framework Core. Migrations run automatically at startup.
  • repos/ holds the bare Git repositories.
  • keys/ holds the keys that protect login cookies. Losing them signs everyone out.
  • Both live under Forge:DataPath. Back up that folder to back up the server.

Project layout

forge/           ASP.NET Core application
  Components/    Shared Blazor components and layout
  Features/      Feature folders: Auth, Browse, History, Pulls, Repos, SmartHttp, Webhooks
  Git/           Thin wrapper around the git executable and its output parsers
  Data/          EF Core model, DbContext and migrations
  Localization/  Translation files (sk.json; English is the source language)
  wwwroot/       Static assets (CSS, JavaScript, syntax highlighting)
forge.Tests/     xUnit tests, including end-to-end tests that run the app and real Git

Development

dotnet build forge.slnx
dotnet test forge.Tests

Adding a language means adding a JSON file to forge/Localization/, named after its culture code (for example de.json). Keys are the English strings exactly as they appear in the code.

Database schema changes are made with the EF Core tools in dotnet-tools.json:

dotnet ef migrations add <Name> --project forge

Security notes

  • Passwords are hashed with ASP.NET Core Identity's PasswordHasher.
  • Access tokens are used as the Git password. Read-only tokens cannot push.
  • Responses set a strict Content-Security-Policy, X-Frame-Options: DENY and nosniff.
  • Form posts are rate limited per client address. Rendered Markdown is sanitized.
  • Webhook receivers are not followed on redirect, so signed payloads are never re-sent to another address.

Keyboard shortcuts

/
Search repositories
s
Search file names and code
y
Open the permalink of the file being viewed
?
Show this help