mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-10 04:36:40 +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>
79 lines
2.3 KiB
Markdown
79 lines
2.3 KiB
Markdown
# System Utility: Git Pull (Shallow & Pinned)
|
|
|
|
## Description
|
|
|
|
This Ansible role provides a **robust, reusable Git pull utility** for system automation.
|
|
It performs shallow clones or updates of Git repositories and optionally **pins the working tree
|
|
to a specific tag** (e.g. `stable`) in a detached HEAD state.
|
|
|
|
The role is designed to solve common automation pitfalls such as:
|
|
|
|
- conflicting local tags (`would clobber existing tag`)
|
|
- detached HEAD updates
|
|
- annotated vs. lightweight tags
|
|
- reliable change detection for Ansible
|
|
|
|
Internally, the role delegates complex Git logic to a small, well-tested Python helper script,
|
|
keeping the Ansible YAML concise and readable.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This role:
|
|
|
|
- Ensures a repository exists at a given destination
|
|
- Clones the repository shallowly if it does not exist
|
|
- Updates an existing repository in a **detached-safe** manner
|
|
- Optionally removes conflicting local tags before fetching
|
|
- Optionally pins the checkout to a specific tag (e.g. `stable`)
|
|
- Marks the Ansible task as `changed` if:
|
|
- the repository was cloned
|
|
- tags were removed
|
|
- the pinned tag appeared for the first time
|
|
- the pinned tag moved on the remote (optional)
|
|
|
|
---
|
|
|
|
## Purpose
|
|
|
|
The purpose of this role is to provide a **generic, reusable Git pull primitive**
|
|
for other roles in the Infinito.Nexus ecosystem.
|
|
|
|
Typical use cases include:
|
|
|
|
- installing tools pinned to a `stable` tag
|
|
- reproducible system deployments
|
|
- CI/CD-friendly shallow clones
|
|
- avoiding fragile inline Git shell logic in roles
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Shallow Clone & Update** (`--depth`)
|
|
- **Detached-safe Branch Updates**
|
|
- **Optional Tag Pinning** (e.g. `stable`)
|
|
- **Annotated Tag Support** (`tag^{}`)
|
|
- **Local Tag Conflict Healing**
|
|
- **Deterministic `changed_when` Semantics**
|
|
- **Verbose Debug Logging (stderr-only)**
|
|
|
|
---
|
|
|
|
## Design Notes
|
|
|
|
- All human-readable logs go to **stderr**
|
|
- Machine-readable state (`CHANGED=…`) is written to **stdout**
|
|
- This guarantees reliable `changed_when` behavior in Ansible
|
|
- The Python helper is intentionally self-contained and unit-testable
|
|
|
|
---
|
|
|
|
## Credits
|
|
|
|
Developed and maintained by **Kevin Veen-Birkenbach**.
|
|
Learn more at [veen.world](https://www.veen.world).
|
|
Part of the [Infinito.Nexus Project](https://s.infinito.nexus/code).
|
|
Licensed under the [Infinito.Nexus Community License (Non-Commercial)](https://s.infinito.nexus/license).
|