Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Forges: git host support
packages/core/src/repowise/core/forges/ holds every fact repowise knows about
a git host (a forge): which hosts it claims, its URL shapes, its CI variables,
its merge-message conventions, its noreply addresses and bot accounts. Callers
ask this package and never match hosts themselves. The user-facing summary is
GIT_HOSTS.md.
Module map
| File | Holds |
|---|---|
base.py |
ForgeKind, RemoteRef, RemoteParts, the Forge protocol, BaseForge defaults, CiSystem, URL and ref helpers |
registry.py |
register, get_forge, all_forges, host resolution (override, then host claim, else generic), forge_hosts and REPOWISE_FORGE_HOSTS |
remote.py |
parse_remote, canonical_key, strip_credentials: pure string work on remote URLs |
detect.py |
read_remote_url (reads .git/config, follows worktrees) and detect_forge (remote, then CI env) |
changes.py |
change_number (the change a commit is) and change_refs (every change it mentions) |
identity.py |
canonical_email, noreply_login, is_bot, plus the bot names shared by every host |
ci.py |
CiContext, detect_ci, and CIs that belong to no forge (Jenkins) |
github.py, gitlab.py, azure.py, bitbucket.py |
One forge each: host claims, path parsing, URL builders, CiSystem, merge forms, identity rules |
generic.py |
The fallback: parses any host/path, builds no URLs, reads GitHub-style messages |
Users: the webhook lookup (server/routers/webhooks.py), git_refs.remote_name,
the overview remote and repository responses (strip_credentials),
core/ci/base.py (CI_ENV_VARS, default_revspec), the git indexer
(change_number), revert matching (analysis/decisions/reverts.py) and
author_identity.py.
Invariants
- Every forge fact lives in its forge's module. A host name, URL shape, noreply domain, bot name or merge convention elsewhere is a bug. New host regexes go in this package, not in their callers.
- Parsers do no I/O.
remote.py,changes.py,identity.pyandci.pyread strings and env mappings only.detect.pyreads.git/configdirectly instead of spawning git;forge_hostsreads the repo config. - Values are frozen, slotted dataclasses (
RemoteRef,CiSystem,CiContextand every forge). Registration replaces a forge; nothing mutates one. - Canonical keys drop the scheme, userinfo, port, query,
.git, trailing slashes and GitLab's/-/web routes, then lowercase the whole key, path included: GitHub and GitLab resolve repo paths case-insensitively, so a registered URL that differs from the webhook's only in case must still match. Azure's three host forms fold todev.azure.com/org/project/_git/repo; Bitbucket Data Center keys ashost/PROJ/repo. - Precision over recall. A wrong change number is worse than none, so only
a merge or squash form sets one; a bare
#N,AB#Nor a link never does. Every merge form needs a literal lead, exactly one capture group and noIGNORECASEflag (lead_ofraises otherwise); write the number as\d{1,9}. For identity, a missed fold beats joining two people: only a forge's provable noreply form folds, and a bot name matches as an explicit marker or a full service name, never a substring. - Identity reads every forge. An address keeps its minting forge's shape
after a move, so
normalize_identitygives the same answer on every forge. - History rules are versioned. Changing a merge form or identity rule
changes stored rows: bump
GIT_HISTORY_VERSIONiningestion/git_indexer/_constants.pyso the next update re-reads the full history once.
Adding a forge
- Add a member to
ForgeKindinbase.py. - Create
forges/<name>.pywith a@dataclass(frozen=True, slots=True)subclass ofBaseForge. - Declare host claims in
claims_host(exact public hosts and aliases; a self-managed install is reached throughforges.hosts). Claims must stay disjoint from every other forge's. - Implement
parse(the forge's path shape,Nonewhen it does not fit) and, if clone and web URLs differ,canonical_path. - Implement the URL builders:
commit_url,change_url,blob_url,compare_url. - Set
labelandchange_term, and overrideformat_change_refif the display is not#N. - Give it a
CiSystem(markers, base branch, head sha, change number, repo URL) if the forge runs its own CI. - Declare merge forms (
merge_subject_res,merge_body_res,native_merge_subject_res,merge_body_first) and implementparse_change_refsfor mentions. - Declare identity rules:
noreply_rewith alogingroup andnoreply_fold,bot_name_re,bot_email_re. - Call
register(...)at module bottom and import the module inforges/__init__.py. - Add rows to each table test under
tests/unit/core/:test_forges_remote.py(parse, key, credentials),test_forges_urls.py(URLs, label, change display),test_forges_change_refs.py(change_number,change_refs),test_forges_identity.py(noreply, bots),test_forges_ci.py(CI env) andtest_forges_detect.py(remote and CI detection). - If a merge form or identity rule changes stored history, bump
GIT_HISTORY_VERSION.
Adding a CI system that is not a forge
A CI that builds repos from any host (Jenkins) gets a CiSystem in ci.py
and an entry in _STANDALONE; standalone CIs are tried after the forges'
own. CI_ENV_VARS and CI_BASE_VARS in core/ci/base.py pick up its markers
and base-branch vars automatically. A CI that is detected by presence alone,
with nothing to read, goes in _PRESENCE_ONLY in core/ci/base.py. Add its
build shapes to CASES in tests/unit/core/test_forges_ci.py.