mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-06 02:54:26 +00:00
kevinveenbirkenbachandClaude Opus 4.7
16bdbf03d7
Three classes of drift cleaned up across 85 .md files:
- Em-dashes: replaced ` — ` with the contextually correct separator
(colon for `term: explanation`, period to split clauses across
sentences/source lines, parentheses for asides, semicolon for
tight-linked continuations). Two intentional exceptions remain
in `docs/contributing/documentation.md` (the rule literal) and
inside a fenced ```sh block in `docs/contributing/actions/debugging/ci.md`.
- SPOT self-labels: rewrote "This is the SPOT for X" to describe
the subject directly ("This directory holds X" / "This file
describes X"). Cross-references to other artefacts' canonical
role remain unchanged.
- Heading-emoji position: moved leading-emoji headings (`# 🧩 Title`)
to trailing position (`# Title 🧩`) per the headline rule that
emojis MUST come after the title text.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
69 lines
4.0 KiB
Markdown
69 lines
4.0 KiB
Markdown
# CI Failures and Debugging 🐛
|
||
|
||
If CI fails, follow a clean debugging workflow:
|
||
|
||
1. Export the raw failing logs.
|
||
2. Save them locally as `job-logs.txt`.
|
||
3. Decide whether the failure belongs to your branch or to something unrelated.
|
||
4. Fix related failures in the same branch.
|
||
5. Open an issue for unrelated failures instead of mixing them into your branch.
|
||
|
||
## Important 🚨
|
||
|
||
- You MUST NOT debug from screenshots alone. Use raw logs.
|
||
- You MUST NOT commit log files to the repository.
|
||
- If a [Playwright](https://playwright.dev/) job fails, you MUST also download the Playwright assets, store them in `/tmp/`, and analyze them together with the logs.
|
||
|
||
## Manual CI Jobs 🎯
|
||
|
||
You SHOULD use targeted manual CI jobs instead of rerunning the full pipeline if you only need one focused check.
|
||
|
||
Prefer the manual workflow in [entry-manual.yml](../../../../.github/workflows/entry-manual.yml):
|
||
|
||
- Select your branch.
|
||
- Use `debian` unless you have a clear reason to use a different distro.
|
||
- Limit the run to the affected app when possible.
|
||
|
||
This gives faster feedback and protects shared CI runners.
|
||
|
||
More information [here](https://hub.infinito.nexus/t/infinito-nexus-ci-cd-debugging-guide/462).
|
||
|
||
## Reproducing Runner Resource Limits Locally 💾
|
||
|
||
Some CI failures (most notably OOM-kills such as [#162](https://github.com/infinito-nexus/core/issues/162), PeerTube plugin install with `rc=137`) only surface under the memory and CPU ceiling of the GitHub-hosted runner and cannot be reproduced on a workstation with plenty of RAM. To reproduce these failures locally, you MUST cap the resources of the top-level `infinito` service in [compose.yml](../../../../compose.yml) to values that match (or undercut) the runner specs below.
|
||
|
||
### GitHub-Hosted Runner Specs
|
||
|
||
All [workflows](../../../../.github/workflows/) target `runs-on: ubuntu-latest`, which maps to the GitHub-hosted standard Linux runner. The effective ceiling depends on the repository's visibility and plan:
|
||
|
||
| Repository / plan | vCPU | RAM | SSD |
|
||
|------------------------------------------|------|--------|-------|
|
||
| Public repo (this repo, `ubuntu-latest`) | 4 | 16 GB | 14 GB |
|
||
| Private repo on Free / Pro / Team | 2 | 7 GB | 14 GB |
|
||
| Private repo on Enterprise | 4 | 16 GB | 14 GB |
|
||
|
||
The effective budget for the actual workload is lower than the table suggests because the runner itself plus the nested `infinito` container (systemd, nested Docker, Ansible) reserve a non-trivial baseline. Plan for roughly **1–2 GB of overhead** before any role deploys a service.
|
||
|
||
For the authoritative specs, see the upstream docs for [standard hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories) and [larger runners](https://docs.github.com/en/actions/using-github-hosted-runners/using-larger-runners).
|
||
|
||
### Env-Var Knobs
|
||
|
||
[compose.yml](../../../../compose.yml) exposes three env vars on the `infinito` service that cap its memory, swap, and CPU ceiling. For the authoritative variable reference (names, defaults, purpose) see the SPOT in [compose.yml.md](../../artefact/files/compose.yml.md). This page SHOULD NOT duplicate that table and MUST link back to it when a contributor needs the precise definitions.
|
||
|
||
### Canonical Reproduction Profiles
|
||
|
||
Pick the profile that matches the runner you want to mimic:
|
||
|
||
```sh
|
||
# Public repo runner (ubuntu-latest, 4 vCPU / 16 GB) — the default CI target
|
||
INFINITO_MEM_LIMIT=16g INFINITO_MEMSWAP_LIMIT=16g INFINITO_CPUS=4 make <target>
|
||
|
||
# Private repo runner on Free/Pro/Team (2 vCPU / 7 GB)
|
||
INFINITO_MEM_LIMIT=7g INFINITO_MEMSWAP_LIMIT=7g INFINITO_CPUS=2 make <target>
|
||
|
||
# Aggressive OOM reproducer — forces the memory spike that surfaces #162
|
||
INFINITO_MEM_LIMIT=4g INFINITO_MEMSWAP_LIMIT=4g INFINITO_CPUS=2 make <target>
|
||
```
|
||
|
||
Verify the caps applied with `docker compose -f compose.yml --profile ci config | grep -E 'mem_limit|memswap_limit|cpus'` before starting the deploy.
|