Forge

Jessie / forge public

Self-hosted git - made by qwen 3.8 27b

commit: 0c9688e9

Branches

main
README.md 5.4 kB · 99 lines RawHistory
# 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](https://dotnet.microsoft.com/download) 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

```bash
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

```bash
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`:

```bash
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