mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-08 11:46:35 +00:00
kevinveenbirkenbachandClaude Opus 4.7
79409ebf10
Tooling integration
* add .markdownlint-cli2.jsonc, .ansible-lint, .ansible-lint-ignore
configs (permissive day-1: cosmetic rules disabled, semantic ones on)
* extend scripts/install/lint.sh with generic install_pip_pkg helper +
ensure_ansible_lint / ensure_galaxy_importer / ensure_markdownlint_cli2
ensure_* functions (pip / npm with sudo / --user / --break-system-packages
fallbacks). install_ansible_tools now also pulls ansible-lint and
galaxy-importer; new `markdown` install group.
* extend scripts/lint/ansible.sh to run ansible-lint after the existing
syntax-check.
* add scripts/lint/markdown.sh and scripts/lint/galaxy.sh runners. The
galaxy runner parallelizes via xargs (-P=$(nproc)), prints OK/FAIL per
role, and treats `bare-name dependency` errors as success since our
roles/ tree is not a Galaxy collection layout. All other Galaxy schema
errors still fail.
* Makefile: new lint-markdown and lint-galaxy targets, both wired into
`make lint`.
* CI: new workflows lint-markdown.yml and lint-galaxy.yml; lint-ansible.yml
now installs ansible-core + ansible-lint; ci-orchestrator wires both
new lint workflows into lint-gate.
Galaxy schema fixes
* shorten the canonical `galaxy_info.company` block from three lines to
two ("Kevin Veen-Birkenbach\nhttps://www.veen.world", 45 chars) so it
stays under Galaxy's hard 50-char limit. Updated everywhere: 229 role
meta/main.yml plus _CANONICAL_COMPANY in
tests/lint/repository/test_role_meta_main_galaxy_schema.py.
* shorten 19 over-long role descriptions to <=255 chars.
* add stub READMEs for sys-svc-compose-ca and sys-utils-service-loader.
Markdown baseline fixes
* markdownlint-cli2 --fix run repo-wide (formatting normalization
across CHANGELOG, role READMEs, docs).
* manual MD041 fixes: prepend H1 in 15 files (CHANGELOG, LICENSE,
TODO.md helpers, role README templates, etc.).
* MD025 / MD003 / MD001 / MD032 manual fixes for heading-style and
list-spacing edge cases.
* role README content polish: "## Single Point of Truth (SPOT)" headings
renamed to "## User data resolution" (D3 self-label rule).
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, `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.
|