Documentation for v2.10.0. Read the latest, v2.12.0.

Operator

Administration

The day-to-day of running an instance: what an administrator sees on /admin.html, the exceptions that need a hand (deleting a version, a Producer, a branch), what expires on its own and when, and the resets that wipe things. Users, roles and authentication have their own chapters.

The admin page#

/admin.html needs a signed-in session. A control the caller may not use is greyed out, never hidden, and its tooltip names the permission it needs (a maintainer grant on the Producer counts for that Producer's buttons); the same holds on the Producer page and the graph. Settings everybody may know (auto-acknowledge, the cleanup ages, the cache size and the ticket template) show their real value to everyone signed in, from GET /admin/instance-settings; the authentication configuration, the webhook allow-list, the database URL, users, groups and maintainers show "Visible to holders of the … permission" to whoever lacks it, and the page does not ask for them. Roles and permissions are described in Roles and permissions, and every route behind it is in the generated Maintenance API with its guard. Top to bottom: In-Memory Cache, Database Configuration, Sanshain-Branches, Webhooks, Trunk Data TTL, Snapshot Cleanup, Ticket Links, Dependency Cleanup, Authentication, Users, Groups, Maintainers, Provide a Spec for a Producer, Producers, Consumers, Danger Zone. Administrative routes accept session tokens only, so a script that administers logs in first (POST /auth/login); the one exception is the backup download, which takes a full API token.

Everything an administrator changes lands in the audit log with the acting user, see below.

Producers and versions#

The unit of administration is the version line. Versions manage themselves for the most part (GA is immutable and never age-culled, snapshots expire when unused), so administration is the exceptions. The Producers section lists every Producer that has provided at least once with its version lines; /producers.html is the richer view for browsing.

Deleting a version#

The sole escape hatch from GA immutability (ADR-0003). Consumers pinned to the deleted version fail with 404 on their next require; the UI shows the dependents and the sanshain-branches whose recorded graph references the version before you confirm. Move the Consumers first where you can. A branch's pin is left visibly dangling rather than dropped, and a later re-provide of the number heals it. The audit entry names the Consumers that were still pinned.

Deleting a Producer or a Consumer#

Refused with 409 while any sanshain-branch's recorded graph references the participant, because its rows would cascade out of release cuts that already happened:

'orders' is part of the recorded graph of sanshain-branch(es) release-2026-10 — deleting it would remove those edges from release cuts that already happened. Delete the branch(es) first if the record is no longer needed.

Trunk presence does not block a delete; trunk is the living stream and ages out on its own TTL. A confirmation dialog precedes every deletion in the UI.

Consumers#

The Consumers section lists every Consumer that has recorded a dependency. GET /admin/consumers, GET /admin/consumers/{name} and GET /admin/consumers/{name}/endpoints are readable by any signed-in caller; DELETE /admin/consumers/{name} (manage_consumers) removes it with its dependencies, audited as DELETE_CLIENT, with the same 409 as above while a branch references it.

Sanshain-branches#

Release cuts (Release graphs). The Sanshain-Branches section creates, renames and deletes them:

• Create (POST /admin/branches, release_ga): a named copy of the main graph, or of another branch, at a chosen instant; a past as_of repairs a forgotten cut. main, dev and trunk are reserved. Emits branch.cut to global webhooks.
• Rename (PUT /admin/branches/{name}, manage_producers): membership, timeline and audit stamps survive, because all key on the branch's id. Pipelines still sending the old tag get a Sanshain-Warning until reconfigured.
• Delete (DELETE /admin/branches/{name}, manage_producers): the end-of-life act; frees the name.

GET /admin/branches, …/{name}/graph, …/{name}/timeline, /admin/trunk/graph, /admin/trunk/timeline, /admin/graph/diff, /admin/graph/scope and /admin/periphery are the read side the graph page uses, open to any signed-in caller. Audited as BRANCH_CREATED, BRANCH_RENAMED, BRANCH_DELETED. There are no "protected branches" in 2.6.0; that older concept was replaced by sanshain-branches.

Retention and cleanup#

One background pass every CLEANUP_INTERVAL_SECS (3600) does all of the following; each ran-now button triggers one step immediately. The ages are settings (Configuration), at most 36500 days.

The settings and the run-now routes need manage_settings. The background pass logs a line when a step removed something (Snapshot cleanup: deleted 3 unused snapshots); the run-now routes write SNAPSHOT_CLEANUP, DEPENDENCY_CLEANUP and TRUNK_CLEANUP audit entries.

Settings#

• Ticket Links: the ticket URL template, an absolute http(s) URL with {id} for the id (https://jira.acme.corp/browse/{id}). The pages render the ticket ids of a version's origin as links with it; empty shows them as plain text (GET /admin/ticket-url-template for every signed-in user, POST /admin/settings/ticket-url-template audited as SET_TICKET_URL_TEMPLATE).
• In-Memory Cache: the memory bound at runtime, hit rate, entries and memory used, and Clear Cache (POST /admin/cache/clear, audited as CLEAR_CACHE). See The data cache.
• Database Configuration: the backend and the connection URL with the password and any password query parameter removed (GET /admin/settings/database), read-only; and on SQLite the snapshot download.
• Authentication: the mode (Off, Dev, Local users, LDAP, OIDC) with the LDAP and OIDC forms, and in Local mode the Registration and Auto-acknowledge new users switches, see Authentication.
• Users: approve, delete and grant roles, and create service accounts for automation.
• Webhooks: global hooks and the Allowed receiver hosts list, see Webhooks.
• Provide a Spec for a Producer: a provide from the browser, for a one-off upload by an administrator, with the same rules as the API.

The audit log#

Every provide, require, catalog push and administrative action writes an audit entry with the acting user, the service and version it concerns and, for stream-bound facts, the stream. /audit.html shows the audit timeline with filters by date, type, Producer and version (SQL wildcards, auth-%) and stream, and a diff viewer on provides; it reads GET /api/audit/timeline (view_audit). The observability page has an audit tab with Export CSV: GET /admin/observability/audit-logs/export returns the newest 1000 entries with the header

id,timestamp,username,action,details,service,version,action_type,stream

The action names, grouped:

The audit log is not a webhook source by design (ADR-0009): a hook for admin events would be a second copy with a weaker access check.

The Danger Zone#

Four resets, all behind run_destructive_operations, each confirmed in the UI by typing the phrase and on the API by sending it as {"confirmation": "…"}; anything else answers 400 Invalid confirmation. Every one writes a NUKE_DATABASE audit entry.

Take a backup first. There is no undo, and the audit entry is the only trace.

Checked against v2.6.0.