Server Inventory: Centralized Telemetry and Access Control for golauncher

Server Inventory is the production hub for my golauncher agent system — a centralized server inventory telemetry repository for collection, release management, and tiered access control across a fleet of deployed server agents. The unusual part: there is no telemetry server, no database, and no API. GitHub itself is the entire backend. GitHub Actions processes telemetry events, Fine-Grained Personal Access Tokens enforce access levels, and binary releases ship through GitHub Releases with SHA-256 verification.

This article walks through how that works in practice, the exact data each agent reports, the three-tier access model, the auto-update mechanism — and, just as importantly, where this pattern breaks down and when you should not use it.

Architecture: GitHub as Infrastructure

The system operates on an unconventional but effective principle: the repository is the database, Git history is the audit trail, and GitHub’s own infrastructure handles availability and scaling. This is a deliberate separation of concerns — the server-inventory repository is production-only: it holds telemetry data, release binaries, and version metadata, but no source code. The agent’s source lives in a separate repository, and access tokens and client configurations never touch the hub at all — they stay on each machine.

That split matters for security. A leak of the production hub exposes operational telemetry, not the logic that collects it or the credentials that authorize it. It also keeps the repository small and auditable: every change is a commit, every telemetry update is attributable, and rolling back is a Git operation rather than a database migration.

The Telemetry Pipeline, Step by Step

When an agent checks in, the flow is fully event-driven and requires no standing service:

1. The golauncher agent opens a GitHub Issue carrying its telemetry as a fenced json block, tagged with the telemetry label.
2. A GitHub Actions workflow triggers on issues: [opened] but runs only if the issue carries the telemetry label — a cheap, declarative filter.
3. A short Python step extracts the JSON between the ```json fences, parses it, and resolves the reporting host’s name.
4. The workflow writes the payload to telemetry/<hostname>.json, regenerates telemetry/dashboard.md, commits both, and closes the issue — all automatically.

The result is a self-maintaining fleet dashboard with zero servers to patch. The Actions runner is ephemeral, the permissions are scoped (contents: write, issues: write) to exactly what the job needs, and a malformed payload fails loudly in the workflow log instead of silently corrupting a database.

Server Inventory Telemetry: What Each Agent Reports

The server inventory telemetry payload is a flat, deliberately small JSON document. Each agent reports:

• Identity — server_name, hostname, and a stable host_id
• Platform — os and architecture
• Reachability — external_ip
• Capacity — disk_free_gb, disk_total_gb, disk_used_percent
• Inventory — an applications list of installed tools, each pinned to its Git commit version
• Provenance — report_timestamp, event type, github_issue number, and a server-side processed_at stamp

That last field — applications with Git commit versions — is the quiet workhorse. It turns the hub into a fleet-wide software bill of materials: at any moment I can answer “which servers are running the old build of a given tool?” with a grep over the telemetry/ directory, no agent round-trip required. The fleet currently spans active Linux and Windows hosts, and the auto-generated dashboard surfaces which servers are live, when they last checked in, and what they’re running.

Three-Tier Access Control

Client access is managed through Fine-Grained Personal Access Tokens at three levels, so a single hub can serve internal, free, and paying clients without separate infrastructure:

• Level 1 (Admin) — full access to every repository including paid tools, for internal servers and debugging
• Level 2 (Free) — access only to free repositories such as linux-network-manager
• Level 3 (Paid) — full access including paid tools like the rocketchat-deploy-toolkit

Two design choices keep this maintainable. First, token references use indirection (ref:tokens/level-2-v1), so rotating a token means updating one file, not reconfiguring every client. Upgrading a client from free to paid is a single YAML edit. Second, enforcement is doubled: the Fine-Grained PAT itself restricts a Level 2 token to repositories without the paid topic, and the agent independently checks an allowed_repos list before it clones anything. A misissued token can’t quietly become a privilege escalation, because the agent refuses repositories its tier shouldn’t see.

Release Management and Auto-Update

Updates run through a single source of truth: releases/version.json. It records the latest version, release date, and — per platform and architecture — a download URL and a SHA-256 checksum. golauncher ships for Linux (amd64, arm64), Windows (amd64), and macOS (amd64, arm64), each binary cross-compiled and checksummed.

Agents poll this file, compare the advertised version to their own, and self-update when a newer build appears — verifying the downloaded binary against its published SHA-256 before swapping it in. The checksum is the trust anchor: even though the binaries are served from GitHub Releases over HTTPS, the agent never runs a download whose hash doesn’t match the manifest. That makes the update path tamper-evident without a separate signing infrastructure.

Why GitHub Instead of Prometheus or a Database?

The honest answer is fit, not dogma. For a fleet of roughly 10–50 servers reporting on check-in rather than streaming metrics, a Prometheus/Grafana stack or a hosted time-series database is more machinery than the problem deserves: another service to run, secure, back up, and pay for. GitHub already provides the API, the storage, the compute (Actions), the access control (Fine-Grained PATs), and the audit trail (Git history) — and for a private repository, all of it at no additional cost.

What I give up is real-time. This is an inventory-and-check-in system, not a metrics pipeline: it answers “what is my fleet, and is each host healthy as of its last report?” — not “what is CPU doing this second?” For that question, the latency of an Issue-plus-Actions round trip is irrelevant.

Where This Pattern Breaks Down

Treating GitHub as a backend has real limits, and pretending otherwise would be dishonest:

• Scale ceiling. Actions minutes and API rate limits are generous for tens of servers and punishing for thousands. Past a few hundred frequently-reporting agents, a purpose-built ingestion service wins.
• Not real-time. Event processing takes seconds to a minute. Anything needing sub-second alerting belongs on a proper monitoring stack.
• Privacy is on you. The telemetry contains hostnames and external IPs, so the repository must stay private — a public hub would be a free reconnaissance map of your fleet. This is the single most important operational rule of the whole design.
• Vendor coupling. The system is bound to GitHub’s availability and product decisions. That’s an acceptable trade for a personal or SMB fleet, less so for something that must survive a provider outage.

Within those bounds, the trade is excellent: near-zero operational cost, a complete audit trail for free, and one less service to keep alive at 3 a.m.

Source Code

The repository and agent source are available upon request — contact me for access. As a Fractional CTO I build lightweight infrastructure that leverages existing platforms instead of reinventing them; this system is a deliberate example of that philosophy. For server management and DevOps consulting, I bring 15 years of managing infrastructure across 38 countries.

FAQ

Why use GitHub Issues for telemetry instead of a database?

Zero infrastructure cost and a free audit trail. GitHub provides the API, storage, processing (Actions), access control, and availability; Git history records every change. For a fleet of 10–50 servers reporting on check-in, this is simpler and more reliable than maintaining a separate telemetry stack — provided the repository stays private.

How does token rotation work?

Tokens are referenced by indirection (ref:tokens/level-2-v1). To rotate, create a new token, save it as a new version file, update the reference, and mark the old token expired. Clients resolve the reference on startup, so the change propagates without touching individual client configurations.

What platforms does golauncher support?

Linux (amd64, arm64), Windows (amd64), and macOS (amd64, arm64). Binaries are cross-compiled and published with SHA-256 checksums in releases/version.json, which agents verify before applying an update.

Can free clients access paid repositories?

No. Fine-Grained PATs restrict Level 2 tokens to repositories without the paid topic, and the agent independently checks allowed_repos before cloning. The two controls enforce the boundary even if one is misconfigured.

Does this scale to hundreds or thousands of servers?

Not comfortably. GitHub Actions minutes and API rate limits suit tens of servers; past a few hundred frequently-reporting agents, a dedicated ingestion service is the better choice. This design optimizes for low operational overhead at small-to-medium fleet sizes, not for unbounded scale.

Need a consultation?

If you need professional expertise — book your free 15-minute consultation.