0 Fork 0

mirror of https://github.com/kevinveenbirkenbach/computer-playbook.git synced 2026-11-06 19:01:54 +00:00

Files

T

kevinveenbirkenbachandClaude Opus 5 c55f508e05 feat(readme): draw mandatory and disabled service relations

The cosmos generator linked a consumer to its provider only through an
'<role>' in group_names reference or an explicit provides: name. A hard
dependency has neither -- pinning the provider on unconditionally is
exactly what removes the Jinja reference the generator was reading -- so
web-svc-asset's bond to web-svc-file vanished from the diagram the moment
it became binding. Match a service key against the provider's own primary
key from the registry, in both directions.

Services the role turns off drew a solid 1:1 edge, claiming a mandatory
relationship for something that carries nothing at deploy time. They now
render as a red 0..0 edge; edge merging gained a real precedence so a
provider consumed through two keys stays live when only one is off.

Named colour, not hex: a '#' opens an entity code in the mermaid lexer and
turns the whole diagram into a parse error on GitHub.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-17 18:02:31 +02:00

3.1 KiB

Raw Blame History

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)

Cosmos

The diagram places System Utility: Git Pull (Shallow & Pinned) in the Infinito.Nexus cosmos: the components it deploys (capabilities), the central services it consumes (dependencies), and its outward reach (federation and bridged external networks).

flowchart LR
    subgraph role [sys-util-git-pull 💻]
        svc_util_git_pull["util-git-pull"]
    end

Solid 1:1 edges are fixed relationships; dashed 0..1 edges are conditional (enabled only in matching deployments); red 0..0 edges are turned off in this role. Node markers show the role's deploy modes (💻 host, 🐳 compose, 🐝 swarm); ❌ marks a service that is explicitly turned off, and ⚙️ an Ansible role dependency declared in meta/main.yml.

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

Implemented by Kevin Veen-Birkenbach. Part of the Infinito.Nexus Project and maintained by Kevin Veen-Birkenbach. Licensed under the Infinito.Nexus Community License (Non-Commercial).

3.1 KiB Raw Blame History