HgLab

A small Bottle app that hosts public Mercurial repositories with local user accounts.

Features include public user profiles, repository browsing, commit diffs with comments, README rendering, issues with comments, fork-based pull requests, repository contributors, and HTTP Mercurial clone/pull/push.

Run locally

python3 -m pip install -r requirements.txt
SECRET_KEY=change-me python3 app.py

Then open http://127.0.0.1:8080, create an account, and create a repository.

Python 3.14 requires Mercurial 7.2 or newer. Older Mercurial releases can fail during startup with hgdemandimport/threading.RLock import errors.

Mercurial client use

Clone and pull are public:

hg clone http://127.0.0.1:8080/hg/<user>/<repo>

Push requires the repository owner's or a contributor's username and password:

hg push http://<user>@127.0.0.1:8080/hg/<user>/<repo>

GitHub-style workflow with bookmarks

Use Mercurial bookmarks as the Git branch equivalent:

• Git main or GitHub default branch: Mercurial bookmark @
• Git feature branch: Mercurial bookmark like feature/xyz
• GitHub PR from same repo branch: HgLab PR from a same-repo bookmark or branch
• GitHub fork PR: HgLab PR from a fork bookmark or branch
• HgLab "Branches" tab: Mercurial named branches, not Git-style branches

Set up the main bookmark once on the commit you consider main:

hg bookmark @
hg push -B @

Create and push feature work from that bookmark:

hg pull -B @
hg update @

hg bookmark feature/xyz
# edit files
hg commit -m "Implement xyz"

hg push -B feature/xyz

HgLab treats @ as the repository's default code ref when it exists. The feature bookmark remains browsable from the Bookmarks tab without replacing the unqualified repository view. Maintainers can also open pull requests from bookmarks and branches in the same repository, so collaborators with push access do not need to fork before asking for review.

Open a pull request in HgLab with:

Source ref: alice/demo bookmark feature/xyz
Target ref: alice/demo bookmark @

For an outside contributor using a fork:

Source ref: bob/demo-fork bookmark feature/xyz
Target ref: alice/demo bookmark @

After merge, update your local main bookmark:

hg pull -B @
hg update @

Optionally delete the feature bookmark locally and remotely:

hg bookmark -d feature/xyz
hg push -B feature/xyz

For GitHub-like branches, prefer hg bookmark. Use hg branch only when you want a permanent Mercurial named branch label in history.

Configuration

• SECRET_KEY: Bottle signed-cookie secret.
• HG_HOST_DB: SQLite database path. Defaults to ./data/hghost.sqlite3.
• HG_HOST_REPO_ROOT: Mercurial repository root. Defaults to ./data/repos.
• HG_HOST_DEBUG: set to 1 for Bottle debug/reloader.
• HG_HOST_MAX_FORM_BYTES: maximum browser form POST size. Defaults to 65536.
• HG_HOST_MAX_RENDER_BYTES: maximum README/file/diff preview size. Defaults to 262144.
• HG_HOST_MAX_HG_RESPONSE_BYTES: maximum buffered Mercurial HTTP response size. Defaults to 268435456.
• HG_HOST_RATE_LIMIT_ENABLED: set to 0 to disable in-memory login/signup/hg auth throttling.
• HG_HOST_RATE_LIMIT_MAX_FAILURES: failed attempts before throttling. Defaults to 5.
• HG_HOST_RATE_LIMIT_WINDOW_SECONDS: rate limit window. Defaults to 300.
• HG_HOST_RATE_LIMIT_COOLDOWN_SECONDS: throttle duration. Defaults to 300.
• PORT: HTTP port. Defaults to 8080.

When HG_HOST_DEBUG is disabled, SECRET_KEY must be set to a non-default value before the app starts.

This v1 stores repositories on local disk. Do not deploy it to ephemeral filesystems unless repository storage is mounted persistently.

SQLite is configured with WAL mode and a busy timeout so a small multi-worker deployment can share one database file. Keep HG_HOST_DB on a local persistent filesystem used by one host; network or synced filesystems can break SQLite locking semantics and should use a server database instead.