majorlinux
21988a2fa9
- New: SELinux Fixing Dovecot Mail Spool Context (/var/vmail) Corrected fix — mail_spool_t only, no dovecot_tmp_t on tmp/ dirs. Includes warning and recovery steps for the Postfix delivery outage. - New: Gitea Actions Runner Boot Race Condition Fix network-online.target dependency, RestartSec=10, /etc/hosts workaround. - Updated SUMMARY.md, index.md, README.md, 05-troubleshooting/index.md - Article count: 37 → 39; MajorWiki-Deploy-Status updated Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
85 lines
3.4 KiB
Markdown
85 lines
3.4 KiB
Markdown
# Gitea Actions Runner: Boot Race Condition Fix
|
|
|
|
If your `gitea-runner` (act_runner) service fails to start on boot — crash-looping and eventually hitting systemd's restart rate limit — the service is likely starting before DNS is available.
|
|
|
|
## Symptoms
|
|
|
|
- `gitea-runner.service` enters a crash loop on boot
|
|
- `journalctl -u gitea-runner` shows connection/DNS errors on startup:
|
|
```
|
|
dial tcp: lookup git.example.com: no such host
|
|
```
|
|
or similar resolution failures
|
|
- Service eventually stops retrying (systemd restart rate limit reached)
|
|
- `systemctl status gitea-runner` shows `(Result: start-limit-hit)` after reboot
|
|
- Service works fine if started manually after boot completes
|
|
|
|
## Why It Happens
|
|
|
|
`After=network.target` only guarantees that the network **interfaces are configured** — not that DNS resolution is functional. systemd-resolved (or your local resolver) starts slightly later. `act_runner` tries to connect to the Gitea instance by hostname on startup, the DNS lookup fails, and the process exits.
|
|
|
|
With the default `Restart=always` and no `RestartSec`, systemd restarts the service immediately. After 5 rapid failures within the default burst window (10 attempts in 2 minutes), systemd hits the rate limit and stops restarting.
|
|
|
|
## Fix
|
|
|
|
### 1. Update the Service File
|
|
|
|
Edit `/etc/systemd/system/gitea-runner.service`:
|
|
|
|
```ini
|
|
[Unit]
|
|
Description=Gitea Actions Runner
|
|
After=network-online.target
|
|
Wants=network-online.target
|
|
|
|
[Service]
|
|
User=deploy
|
|
WorkingDirectory=/opt/gitea-runner
|
|
ExecStart=/opt/gitea-runner/act_runner daemon
|
|
Restart=always
|
|
RestartSec=10
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
Key changes:
|
|
- `After=network-online.target` + `Wants=network-online.target` — waits for full network stack including DNS
|
|
- `RestartSec=10` — adds a 10-second delay between restart attempts, preventing rapid failure bursts from hitting the rate limit
|
|
|
|
### 2. Add a Local /etc/hosts Entry (Optional but Recommended)
|
|
|
|
If your Gitea instance is on the same local network or reachable via Tailscale, add an entry to `/etc/hosts` so act_runner can resolve it without depending on external DNS:
|
|
|
|
```
|
|
127.0.0.1 git.example.com
|
|
```
|
|
|
|
Replace `git.example.com` with your Gitea hostname and the IP with the correct local address. This makes resolution instantaneous and eliminates the DNS dependency entirely for startup.
|
|
|
|
### 3. Reload and Restart
|
|
|
|
```bash
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl restart gitea-runner
|
|
sudo systemctl status gitea-runner
|
|
```
|
|
|
|
Verify it shows `active (running)` and stays that way. Then reboot and confirm it comes up automatically.
|
|
|
|
## Why `network-online.target` and Not `network.target`
|
|
|
|
| Target | What it guarantees |
|
|
|---|---|
|
|
| `network.target` | Network interfaces are configured (IP assigned) |
|
|
| `network-online.target` | Network is fully operational (DNS resolvers reachable) |
|
|
|
|
Services that need to make outbound network connections (especially DNS lookups) on startup should always use `network-online.target`. This includes: mail servers, monitoring agents, CI runners, anything that connects to an external host by name.
|
|
|
|
> [!note] `network-online.target` can add a few seconds to boot time since systemd waits for the network stack to fully initialize. For server contexts this is always the right tradeoff.
|
|
|
|
## Related
|
|
|
|
- [Managing Linux Services with systemd](../01-linux/process-management/managing-linux-services-systemd-ansible.md)
|
|
- [MajorWiki Setup & Publishing Pipeline](majwiki-setup-and-pipeline.md)
|