workshopsoft/ludic
2
0
Fork 0
Code Issues Pull requests Projects Releases 26 Packages Wiki Activity Actions

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

Browse source 
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
Download patch file Download diff file Expand all files Collapse all files

33
CONTRIBUTING.md
View file

@ -176,6 +176,39 @@ non-destructive version of "tidy the history" without touching a single commit.
- Fill in the PR template checklist. Reference the issue you close with
`Closes #NN` in the description or a commit message.
## CI (self-hosted runners)
Every workflow starts by cloning `${{ github.server_url }}/${{ github.repository }}`.
On a self-hosted Forgejo runner that URL is usually the instance's *internal*
address (e.g. `http://forgejo:3000`), so **the job container must be able to
resolve it**. The runner puts each job on a fresh per-job network by default,
which the Forgejo container is not attached to — so the clone fails with:
```
fatal: unable to access 'http://forgejo:3000/…': Could not resolve host: forgejo
```
Give the runner a config that pins job containers to a network Forgejo is also
on. A dedicated network is better than the general application network, so a CI
job cannot reach unrelated services:
```yaml
# the runner's config.yml, passed with: forgejo-runner daemon --config …
container:
network: forgejo-ci
```
with `forgejo-ci` attached to the Forgejo container as well. Verify it without
running a workflow:
```bash
docker run --rm --network forgejo-ci alpine:3 getent hosts forgejo
```
This failure mode is intermittent if left unfixed: Docker forwards names it
cannot resolve to the host's resolver, which may answer for the container name
often enough that CI looks healthy for a while.
## Reporting issues
Use the templates under [`.forgejo/issue_template/`](.forgejo/issue_template):

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.