Appearance
Git Info
Concept layer — frozen. The Git Info generic. Nothing here is written by a normal playbook run; a project's own feature analysis is the live document and takes every edit. This layer names no project and links to none — the dependency runs one way, from an application to its concept.
Business Context
A deployed artefact looks exactly like the one it replaced, and the question that follows every release — is what is running the thing we released? — is normally answered by a pipeline record or a change ticket. Those say what was intended; neither observes what is. The concept closes the gap by making the artefact identify itself. The value is not the data — a commit identifier already sits in a dozen places — it is that this copy was observed rather than looked up.
Business-Level Definition
A build stamp is a closed set of facts fixed by the pipeline that produced the artefact and bound to it — ideally carried inside it, otherwise attached to the deployment of exactly that artefact: a source revision identifier, a build timestamp, and the line of development it came from. Nothing in the running artefact can compute them, so whatever produces it stamps them in and they are inert thereafter. A project that attaches rather than embeds says so, and says what keeps the two from drifting — a redeploy that changes the stamp under an unchanged artefact is a wrong answer, not a new build.
A liveness signal, measured when the question is asked, is often attached to the same answer — a different kind of fact, and whether the two belong together is a decision rather than a given.
Requirements Definition
- The build is established by observing the artefact, without reaching the pipeline, host or logs.
- The set of facts is closed and decided once; this feature's whole cost lies in what gets added afterwards.
- Who may ask, where, and what they get back is decided per project and written down.
Technical Context
User Stories / Use Cases
- As someone verifying a release, I confirm from the environment itself that the build I meant to deploy is the one serving.
- As someone diagnosing an incident, I establish which revision produced the behaviour in front of me.
- As someone accountable for exposure, I find the decision about who may ask already written down.
UI/UX Design
No surface of its own. Where a product renders the stamp in an interface — a footer, an about screen, a support form — that surface is a consumer of the concept and inherits its exposure decision.
Internationalization & Localization
No user-facing text: identifiers and timestamps are technical values and are not translated. The timestamp is serialised absolutely, since its reader is rarely in the time zone of the machine that built it.
Functional Requirements
A closed set of facts
- A source revision identifier, precise enough to locate that revision exactly.
- A build timestamp — when the artefact was produced.
- A source line name — branch, tag or release line: nothing the revision does not already say, and the part a human recognises.
No fourth fact arrives without a decision. Host names, file paths, dependency inventories, the person who triggered the build: each is individually defensible, and the aggregate is a map of the system.
Stamped, never derived. A value can therefore be wrong without being absent: a pipeline stamping from the wrong place answers confidently, and the check meant to catch a bad deployment certifies it instead. If the stamp is attached at deployment rather than embedded, the "build timestamp" is the deployment timestamp; name it honestly.
One stamp per artefact. Each independently deployed artefact carries and answers for its own stamp; one artefact must not answer for another — that two of them disagree is how a stale deployment of one is spotted. A client distributed through a store cannot be asked over the wire: it is either out of this concept's scope or served by an about screen that consumes the same stamp.
When a value was never stamped — a choice. Answer with a placeholder, and environments that never ran the pipeline keep working, at the cost of a diagnostic that degrades quietly: "nobody stamped this" reads as "nothing is deployed here". Or refuse to start, and the stamp becomes an invariant every environment must produce, including those where it is pointless.
Exposure is enforced in one place, ahead of any reading, against an environment indicator the project names in its own analysis. The indicator must distinguish every environment the rule names; an indicator shared by two environments makes them one for this purpose, and an environment that never set it falls to whichever side the rule treats as the default — the closed side, silently, is the better of the two accidents. Which answer it enforces is Who may ask, below.
Non-Functional Requirements
- The stamp costs nothing to produce; any expense belongs to the liveness probe, and an expensive probe is the one disabled during the incident it was built for.
- That probe is read-only, takes no locks, and has a bounded timeout of its own — seconds, not the pool default, and shorter than any probe or ingress timeout in front of it: a diagnostic that hangs when the system is unwell has inverted its purpose. Nothing is cached.
Processes & Related Systems / Components
Spanning a pipeline and a runtime makes this the rare feature whose correctness is mostly settled before any code executes.
Related concepts: Permission Model (where the answer is gated rather than blocked), Multi-Organizations / tenant scoping (the response belongs to no scope — an exception worth naming as one), Config Store (exposure is deployment configuration).
Diagrams & Models
The single question: the exposure rule that answers first, and the two sources the answer is assembled from.
sequenceDiagram
actor A as Caller
participant E as The read
participant B as Build stamp (fixed at build time)
participant D as A dependency (only where a liveness signal is offered)
A->>E: Ask what is running
E->>E: Resolve the environment, apply the exposure rule
alt This environment does not answer
E-->>A: Refused, and nothing is read
else This environment answers
E->>B: Read revision, source line, build time
B-->>E: The stamped values, or the placeholder where one was never stamped
opt A liveness signal is part of the answer
E->>D: Minimal probe, short timeout
D-->>E: Confirmed, or not confirmed within the timeout
end
E-->>A: The build stamp, and the liveness signal where offered
end
Two things the diagram makes hard to miss: the rule answers before anything is read, and an unconfirmed dependency produces an answer rather than a failure.
API Analysis (API-A)
One possible shape of the read: Git Info API. Treat it as an illustration — one path, four field names, a placeholder string, one envelope choice. A project owes its own answer to each.
Domain Model & Data Attribute Table
No entity and no table. Every value is stamped into the artefact at build time or measured on request, so nothing is written and nothing persists between requests.
Data
Nothing to seed: the stamp arrives with the artefact, or with the deployment of exactly that artefact. A value seeded into an environment would describe that environment rather than its build.
Logging & Monitoring
.warn— at minimum: a value that was never stamped, naming which one, since the placeholder in an unrequested response is otherwise its only trace; and a probe that did not confirm..info— the question was asked: the resolved environment, the values returned, the liveness result. Worth emitting where the read is restricted, where each access is a fact about who holds a credential; where the read is open, it is traffic, and call volume (see Auditing) is the signal.
Alerting on an unconfirmed dependency belongs to the health alerting the project already runs.
Backward Compatibility and Migration
The field set becomes a contract the moment anything parses it — a release script, a smoke test, a support form, callers rarely thought of as clients. Adding a field is safe, renaming or removing one is not, and narrowing exposure breaks them without touching the schema at all.
Legal Context
Little here is regulated, but "little" is not "none", and these are worth asking once.
- Does the response identify anything beyond the build? The stamp describes an artefact, not a person, so data-protection questions do not reach it — but only while the field list holds. A machine, a path or the builder's name changes that.
- Is the deployed version something the project must prove? Some contracts and assurance regimes require showing which version served a given request. This concept keeps no history, so that obligation is not discharged here.
- Does revealing the revision breach anything the project agreed to? A commit identifier is rarely confidential, but a customer-facing environment disclosing repository detail can sit awkwardly against a confidentiality clause.
Cybersecurity Considerations
An unauthenticated diagnostic is an exception to default deny and must be recorded as one. A project that makes this read public is stating that the stamp is not worth protecting in that environment — which may well be true, and is a position rather than an oversight. Write it down with its reason, beside the exposure rule. The alternative is to gate it like everything else and accept that the caller must hold a credential.
Neither choice relaxes the field list: a closed payload is what keeps the public answer defensible.
Risk Assessment
The exposure rule is the risk, and its failure mode is silence. A rule written against an indicator the deployment does not set never fires, and nothing errors: the restricted environment answers exactly as the permissive one does, until somebody thinks to check.
- A silently open diagnostic. An unintended caller learns the running revision and, where a liveness signal is attached, whether the system is under strain — together, which published vulnerabilities apply and when to try them.
- False confidence. A verification step that can lie is worse than none: it is used to close incidents, not to open them.
- One probe is not a health model, and where orchestration is pointed at this read it collides with the exposure rule outright — see A liveness signal is a second feature.
- Residual, deliberately not mitigated: nothing detects a rule that never fires. A test asserts that the restricted branch refuses, but only against the value the test itself sets — the same assumption the rule makes. Closing it needs a check against a deployed environment.
Auditing, Reporting & Measurement
A read-only diagnostic changes nothing, so there is no state change to audit. What is worth recording is the access, and how much that matters follows from the exposure decision.
- Where the read is open, its call volume is the only signal there is. An unauthenticated route that suddenly attracts traffic is worth noticing.
- A refusal is more interesting than a success. If the exposure rule fires, something is calling a read that should not be reachable there — and it is the only positive evidence that the rule works.
Who may ask — the decision this concept declines to make
Three answers, all defensible. Which is right depends on who operates the system and how a release gets verified.
Refuse in the environments that matter. The smallest attack surface. Its cost is that the environment where the question is hardest to answer by other means is the one that will not answer it: verification falls back to the pipeline records this concept exists to avoid trusting.
Require authentication. The answer stays available everywhere and reaches only callers the system already knows, which suits a product whose operators are its own staff. It costs a dependency on the authentication path — so the read cannot diagnose an incident in that path — and a credential for the automation that asks.
Answer everywhere, reduced. A shortened revision identifier and nothing else, where the environment is sensitive. Verification keeps working for everyone, at the cost of a permanently public fact and a second response shape to maintain.
Record which was chosen, which environments it covers, what identifies an environment, and where it is enforced. Neither the open answer nor the closed one is wrong; the undocumented answer is. A change to the answer is a decision of the same weight as the original and is recorded in the same place, with its reason — a commit message is not that place, and a rule removed in code while the record still says it holds is the undocumented answer wearing a documented one.
A liveness signal is a second feature
Attaching "is a dependency reachable" to "which build is this" is nearly free, and the same person wants both at the same moment. That is the whole case for bundling them, and it is a good one.
Against it: the two have opposite exposure requirements. A build stamp is something a project may reasonably restrict; a liveness signal that orchestration points at must answer in every environment, unauthenticated, or the platform concludes the artefact is dead. Bundled, both cannot hold, and the restriction is what gets quietly dropped — at which point the decision above was made by accident.
Separating them is cheap: one read orchestration owns, exposing nothing beyond reachability, and one that carries the stamp under whatever rule the project chose.
Known instances
None recorded in this copy. Add this project's instance here as it adopts the concept — one line naming the feature that implements it. This is the only place a concept may name a project, and the template ships it empty so a fork inherits no other project's entries.