From c0c573f7af072f17f3fc90ac676ce4e643f79712 Mon Sep 17 00:00:00 2001
From: Roshan Ramani <154859727+rawsun007@users.noreply.github.com>
Date: Fri, 18 Sep 2026 00:53:40 +0530
Subject: [PATCH] docs: correct ALLOW_LOCALNETWORKS description in
 app.example.ini (#39240)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes the `app.example.ini` half of #39224.

The comment says:

> If a domain is allowed by `ALLOWED_DOMAINS`, this option will be
ignored.

That is no longer true. `checkByAllowBlockList` in
`services/migrations/migrate.go` consults the block list **first** and
returns immediately:

```go
if blockList.MatchHostName(hostName) || ipBlocked {
    return &git.ErrInvalidCloneAddr{Host: hostName, IsPermissionDenied: true}
}
// if we have an allow-list, check the allow-list before return to get the more accurate error
if !allowList.IsEmpty() { ... }
```

`IsMigrateURLAllowed` resolves the host with `net.LookupIP` and passes
the addresses in, so with `ALLOW_LOCALNETWORKS = false` a host that
appears in `ALLOWED_DOMAINS` is still rejected once any resolved address
is private or loopback — the allow list never gets a look. The reporter
traced this to the validation hardening in #38324 / #38400, and the code
matches their description.

The new wording states the precedence rather than the old override
claim.

Scope: this only covers `custom/conf/app.example.ini`, which lives here.
The same stale sentence is on the config cheat sheet in `gitea/docs`
(both the English and zh-cn pages) per the issue; that is a separate
repository.

Assisted-by: Claude, via Claude Code
---
 custom/conf/app.example.ini | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/custom/conf/app.example.ini b/custom/conf/app.example.ini
index 08b12ee4891..06d1bf9076f 100644
--- a/custom/conf/app.example.ini
+++ b/custom/conf/app.example.ini
@@ -2803,7 +2803,8 @@ LEVEL = Info
 ;BLOCKED_DOMAINS =
 ;;
 ;; Allow private addresses defined by RFC 1918, RFC 1122, RFC 4632 and RFC 4291 (false by default)
-;; If a domain is allowed by ALLOWED_DOMAINS, this option will be ignored.
+;; When false, migration URLs are rejected if any resolved address is private or loopback,
+;; even when the host matches ALLOWED_DOMAINS: the block list is applied before the allow list.
 ;ALLOW_LOCALNETWORKS = false
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;