docs(ci): document the runner network a self-hosted CI needs
All checks were successful
bootstrap / cfree-fixpoint (push) Successful in 25s
ci / build-and-test (push) Successful in 2m54s
commit-lint / conventional-commits (push) Successful in 5s

Every workflow's first step clones ${{ github.server_url }}, which on a
self-hosted Forgejo instance is an internal address like http://forgejo:3000.
The runner's default is to put each job on a freshly created per-job network
that the Forgejo container is not attached to, so the clone dies with

    fatal: unable to access 'http://forgejo:3000/…': Could not resolve host

Nothing in the repo said so, and the failure is intermittent: Docker forwards
names it cannot resolve to the host's resolver, which answered for the container
name often enough that CI passed for weeks before stopping.

Documents the fix (pin job containers to a network Forgejo is also on, using a
dedicated one rather than the general application network so a CI job cannot
reach unrelated services) and how to verify it without running a workflow.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Orkun ÇAKILKAYA 2026-09-05 02:57:09 +03:00
parent 0a3df45d20
commit 266e8cdd86
2 changed files with 41 additions and 0 deletions

8
changes/ci-runner-dns.md Normal file
View file

@ -0,0 +1,8 @@
bump: patch
type: docs
CONTRIBUTING documents what a self-hosted Forgejo runner needs for CI to work at
all: every workflow clones `${{ github.server_url }}`, which on a self-hosted
instance is an internal address, so job containers must be able to resolve it.
The runner's default is a fresh per-job network the Forgejo container is not on,
which fails the clone — intermittently, because Docker forwards unresolved names
to the host resolver, so CI can look healthy for a while before it stops.