Support instances that serve SSH from another hostname

Discovery matched a git remote's host against the instance URL's host, so
a server answering SSH on a different name than its web UI resolved to
nothing — and said so only in a debug log.

Resolution now runs in three stages. A remote host is matched directly,
then against configured aliases, and failing both the instances are asked
for the repository: Gitea publishes its SSH hostname in a repository's
ssh_url, so the right instance identifies itself. What that turns up is
saved as a host alias, so later repositories on the same host resolve
with no lookup at all, and the mapping is visible and editable rather
than hidden. Each unknown host is probed at most once per session.

When nothing resolves the sidebar now names the unmatched host and offers
Add Host Alias, instead of showing an empty section.

Aliases can also be written by hand as "remote-host = instance URL",
accepting =, -> and =>, ignoring ports, and skipping # comments. List
preferences now merge workspace entries onto global ones rather than
letting an empty global array mask them.

Adds Tests/host-aliases.test.js covering both directions: unmatched hosts
reported and nothing persisted, a hand-written alias, detection from
ssh_url, and a later repository resolving from the stored alias without a
probe. 131 checks across three suites.

Also adds CLAUDE.md, and .gitea/workflows/ci.yml running the suites,
script syntax checks, manifest validation, and a generated-image check.
Tools/make-icons.py gains --check, which compares decompressed pixels so
a differing zlib version cannot fail it spuriously.

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MQuusXgZC2dzwpJJ1qhtti

Scripts/gitea/router.js

@@ -1,17 +1,24 @@
 //
 // Instance routing. Repositories are matched to a configured Gitea instance by
-// their git remote's host; anything unmatched falls back to the default one.
+// their git remote's host, directly or through a configured host alias for
+// servers that answer SSH on a different hostname than the web UI.
 //
 
 const config = require("../util/config.js");
 const credentials = require("./credentials.js");
+const log = require("../util/log.js");
 const remotes = require("./remotes.js");
 const { GiteaClient } = require("./client.js");
 const { GiteaApi } = require("./api.js");
 
+// "ssh.example.com = https://git.example.com", also accepting -> and =>.
+const ALIAS_SEPARATOR = /\s*(?:=>|->|=)\s*/;
+
 class InstanceRouter {
     constructor() {
         this.apis = new Map();
+        this._aliases = null;
+        this._probedHosts = new Set();
     }
 
     /** Base URLs of every configured instance, default first. */
@@ -36,12 +43,49 @@ class InstanceRouter {
         return urls.length ? this.apiFor(urls[0]) : null;
     }
 
-    /** The instance whose host matches `host`, or null when none does. */
+    /**
+     * Alternate remote hosts mapped onto instance hosts, parsed from the
+     * "remote-host = instance" preference entries. Blank lines, comments, and
+     * malformed entries are ignored rather than breaking discovery.
+     */
+    get aliases() {
+        if (this._aliases) return this._aliases;
+
+        const map = new Map();
+        for (const entry of config.hostAliasEntries()) {
+            const text = String(entry || "").trim();
+            if (!text || text.startsWith("#")) continue;
+
+            const parts = text.split(ALIAS_SEPARATOR);
+            if (parts.length !== 2) continue;
+
+            const from = remotes.hostOf(parts[0]);
+            const to = remotes.hostOf(parts[1]);
+            if (from && to && from !== to) map.set(from, to);
+        }
+
+        this._aliases = map;
+        return map;
+    }
+
+    /**
+     * The instance whose host matches `host`, directly or through an alias, or
+     * null when none does.
+     */
     baseUrlForHost(host) {
         if (!host) return null;
-        const target = host.toLowerCase();
+        const target = String(host).toLowerCase();
+        return (
+            this._instanceForHost(target) ||
+            this._instanceForHost(this.aliases.get(target)) ||
+            null
+        );
+    }
+
+    _instanceForHost(host) {
+        if (!host) return null;
         for (const baseUrl of this.baseUrls) {
-            if (remotes.hostOf(baseUrl) === target) return baseUrl;
+            if (remotes.hostOf(baseUrl) === host) return baseUrl;
         }
         return null;
     }
@@ -54,8 +98,53 @@ class InstanceRouter {
     /** Drops cached clients and tokens so the next call re-reads preferences. */
     invalidate() {
         this.apis.clear();
+        this._aliases = null;
+        this._probedHosts.clear();
         credentials.invalidate();
     }
+
+    /**
+     * Works out which instance serves `host` by asking each one for the
+     * repository and comparing the clone URLs it reports. Gitea publishes its
+     * SSH hostname in a repository's ssh_url, so a server that answers SSH on a
+     * different name than its web UI identifies itself here.
+     *
+     * Probes each host at most once per session and remembers what it learns.
+     */
+    async detectHostAlias(host, owner, name) {
+        if (!host || !owner || !name) return null;
+        if (this._probedHosts.has(host)) return null;
+        this._probedHosts.add(host);
+
+        for (const baseUrl of this.baseUrls) {
+            if (!credentials.hasToken(baseUrl)) continue;
+
+            let repository;
+            try {
+                repository = await this.apiFor(baseUrl).repository({ owner: owner, name: name });
+            } catch (error) {
+                log.debug(`${baseUrl} does not serve ${owner}/${name}:`, String(error.message || error));
+                continue;
+            }
+
+            const advertised = [repository.ssh_url, repository.clone_url, repository.html_url]
+                .map((url) => remotes.hostOf(url))
+                .filter(Boolean);
+            if (!advertised.includes(host)) continue;
+
+            this.rememberAlias(host, baseUrl);
+            log.info(`detected that git remotes on ${host} belong to ${baseUrl}`);
+            return baseUrl;
+        }
+
+        return null;
+    }
+
+    /** Records an alias for this session and persists it for the next one. */
+    rememberAlias(host, baseUrl) {
+        this.aliases.set(remotes.hostOf(host), remotes.hostOf(baseUrl));
+        config.addHostAlias(host, baseUrl);
+    }
 }
 
 exports.InstanceRouter = InstanceRouter;