README
¶
go-version-watcher
Polls https://go.dev/dl/?mode=json on an interval, computes the maximum stable:true Go version, and publishes one deduplicated CreateTaskCommand to Kafka per new version so a downstream task system can act on it.
The emitted task title and body are plain, deployment-agnostic defaults out of the box; set TASK_TITLE_TEMPLATE / TASK_BODY_TEMPLATE (Go text/template) to inject deployment-specific content — e.g. a link to your own update runbook.
The watcher is the producer (Layer 1 detection) half of the pipeline. It never modifies any repo. It emits one global "new Go released" signal; deciding which repos need a bump is a future Layer 2 fan-out service.
How It Works
On each poll cycle:
- Load cursor (
/data/cursor.json) — a singlelast_seen_versionstring. - Query go.dev — parse the JSON release list, keep
stable:trueentries, and compute the max version by parsed(major, minor, patch)integers (go1.26.10 > go1.26.9). On query/parse failure the cursor is held and the cycle recordsgo_dev_error. - Cold start (empty cursor): seed the cursor to the current max and emit nothing — avoids a spurious "update" task on first run.
- New version (
max > cursor): classifyrelease_kind(minorif the major/minor differs, elsepatch), publish oneCreateTaskCommand, and advance the cursor on publish success. - Unchanged (
max <= cursor): recordversion_unchanged, emit nothing.
Deterministic UUID5("go-version:" + version) gives controller dedup — re-polling an already-seen version is a no-op.
Task Contract
Every emitted CreateTaskCommand carries this frontmatter shape:
task_type: go-version-update
assignee: human
phase: planning
status: in_progress
stage: dev|prod
task_identifier: <UUID5("go-version:" + new_version)>
title: Update Go to <X.Y.Z>
new_version: go1.27.0
previous_version: go1.26.5
release_kind: minor # minor | patch
release_notes_url: https://go.dev/doc/devel/release#go1.27.0
Body is an operator-readable header only (title + release-notes URL + downloads URL). The built-in default is deployment-agnostic; override it per deployment with TASK_BODY_TEMPLATE to add e.g. a runbook link.
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
STAGE |
yes | — | Deployment stage (dev or prod) |
KAFKA_BROKERS |
yes | — | Comma-separated Kafka broker list |
LISTEN |
no | :9090 |
HTTP listen address (/healthz, /readiness, /metrics) |
POLL_INTERVAL |
no | 24h |
Poll interval (Go duration string) |
CURSOR_PATH |
no | /data/cursor.json |
Cursor persistence path (PVC mount) |
TOPIC_PREFIX |
no | — | Kafka topic prefix for CQRS topic construction |
SENTRY_DSN |
no | — | Sentry DSN for error tracking |
SENTRY_PROXY |
no | — | HTTP proxy URL for Sentry transport |
HTTP Endpoints
| Path | Method | Purpose |
|---|---|---|
/healthz |
GET | Liveness probe (always 200 OK) |
/readiness |
GET | Readiness probe (always 200 OK) |
/metrics |
GET | Prometheus metrics |
Metrics
| Metric | Cardinality | Purpose |
|---|---|---|
go_version_watcher_poll_cycle_total{result} |
result=success|go_dev_error |
Poll health |
go_version_watcher_published_total{status} |
status=create|error |
Task emission |
go_version_watcher_filter_skipped_total{reason} |
reason=version_unchanged |
Filter visibility |
Development
make test # run unit tests
make generate # regenerate counterfeiter mocks
make precommit # format + lint + test + security checks
Smoke Test (cmd/run-once)
Single Poll cycle against real dev Kafka, then exits.
cd cmd/run-once
make run-once KAFKA_BROKERS=<brokers>
License
BSD 2-Clause License. See LICENSE.
Documentation
¶
Overview ¶
Command go-version-watcher polls https://go.dev/dl/?mode=json on an interval, computes the max stable Go version, and publishes one CreateTaskCommand to Kafka per new version so the Go update runbook can be run.
See [[Go Version Watcher]] for scope + DoD; [[Watcher Writing Guide]] for the producer-side contract; [[Agent Task File Contract]] for the frontmatter/body shape this watcher emits.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
run-once
command
Command go-version-watcher-run-once runs a single go.dev poll cycle then exits.
|
Command go-version-watcher-run-once runs a single go.dev poll cycle then exits. |
|
Code generated by counterfeiter.
|
Code generated by counterfeiter. |
|
Package pkg provides the core domain types and logic for the go-version-watcher service:
|
Package pkg provides the core domain types and logic for the go-version-watcher service: |
|
factory
Package factory wires concrete dependencies for the go-version-watcher binary.
|
Package factory wires concrete dependencies for the go-version-watcher binary. |
|
tasktemplate
Package tasktemplate holds the built-in default title/body templates for the emitted go-version task, authored as embedded markdown files.
|
Package tasktemplate holds the built-in default title/body templates for the emitted go-version task, authored as embedded markdown files. |