amtronics/platform-actions

Watch

Fork 0

docs: Record how the error-reporting DSN is named #73

Merged

ahmad merged 1 commit from feature/64-dsn-naming into main

2026-09-09 12:43:35 +00:00

ahmad commented

2026-09-09 10:19:10 +00:00

Owner

Issue

Closes #64

Problem

The same GlitchTip DSN is stored under two different names across the
fleet, and someone wiring a third repository has no rule to copy —
ahmad/expiro and ahmad/larda are both precedents and they disagree.
The decision was taken on #64; this records it where the next person will
look, which is the only reason the disagreement stops recurring.

Solution

A short subsection in the README's contract section, beside the other
fleet conventions:

VITE_GLITCHTIP_DSN — read at build time, compiled into the bundle,
readable by anyone who loads the page, and therefore a Forgejo
variable in the app's variables.yml.
GLITCHTIP_DSN — read at runtime by the server process only, and
therefore a vault secret in OpenBao secret/<app>.

It states why collapsing them into one name is the mistake: a single
rotation would touch both scopes, and a value that is public by
construction would live in the store meant for private ones. It also
notes that the VITE_ prefix is what makes the bundler expose the value,
so the public one cannot be renamed even if someone wanted to.

Review notes

No workflow changes, in this repository or any other. The decision on #64
was explicitly that no repository is renamed: ahmad/larda keeps
GLITCHTIP_DSN and maps it to the VITE_GLITCHTIP_DSN build arg, which
is correct and stays; ahmad/expiro keeps VITE_GLITCHTIP_DSN and
already has a separate GLITCHTIP_DSN for its api. Nothing loses a
working secret and no deploy breaks on a name that moved.

markdownlint-cli2@0.23.2 — the exact version the README lint step runs
— exits 0 on this file.

The last paragraph is deliberate rather than padding: a DSN can submit
events and not read them, so a leaked browser DSN is noise rather than a
disclosure. Without that, the natural reading of "public by construction"
is that someone was careless, and the next person tries to hide it.

Risks and trade-offs

Documentation only. The risk is the ordinary one for a convention: it is
recorded in a README rather than enforced by anything, so a repository
can still deviate silently. Enforcing it would mean a check that reads
every consumer's variables and secrets, which is worth doing only if it
turns out to drift again.

### Issue Closes #64 ### Problem The same GlitchTip DSN is stored under two different names across the fleet, and someone wiring a third repository has no rule to copy — `ahmad/expiro` and `ahmad/larda` are both precedents and they disagree. The decision was taken on #64; this records it where the next person will look, which is the only reason the disagreement stops recurring. ### Solution A short subsection in the README's contract section, beside the other fleet conventions: - `VITE_GLITCHTIP_DSN` — read at build time, compiled into the bundle, readable by anyone who loads the page, and therefore a Forgejo **variable** in the app's `variables.yml`. - `GLITCHTIP_DSN` — read at runtime by the server process only, and therefore a **vault secret** in OpenBao `secret/<app>`. It states why collapsing them into one name is the mistake: a single rotation would touch both scopes, and a value that is public by construction would live in the store meant for private ones. It also notes that the `VITE_` prefix is what makes the bundler expose the value, so the public one cannot be renamed even if someone wanted to. ### Review notes No workflow changes, in this repository or any other. The decision on #64 was explicitly that **no repository is renamed**: `ahmad/larda` keeps `GLITCHTIP_DSN` and maps it to the `VITE_GLITCHTIP_DSN` build arg, which is correct and stays; `ahmad/expiro` keeps `VITE_GLITCHTIP_DSN` and already has a separate `GLITCHTIP_DSN` for its api. Nothing loses a working secret and no deploy breaks on a name that moved. `markdownlint-cli2@0.23.2` — the exact version the README lint step runs — exits 0 on this file. The last paragraph is deliberate rather than padding: a DSN can submit events and not read them, so a leaked browser DSN is noise rather than a disclosure. Without that, the natural reading of "public by construction" is that someone was careless, and the next person tries to hide it. ### Risks and trade-offs Documentation only. The risk is the ordinary one for a convention: it is recorded in a README rather than enforced by anything, so a repository can still deviate silently. Enforcing it would mean a check that reads every consumer's variables and secrets, which is worth doing only if it turns out to drift again.

ahmad added 1 commit

2026-09-09 10:19:10 +00:00

docs: Record how the error-reporting DSN is named

PR / validate (pull_request) Successful in 22s

Details

66bf5e03ac

Two repositories store the same kind of value under different names and
a third has no rule to copy. Record the convention where fleet
conventions live: VITE_GLITCHTIP_DSN is the build-time value, public by
construction, and belongs in variables.yml; GLITCHTIP_DSN is the api's,
private, and lives in the vault.

Closes #64

ahmad commented

2026-09-09 10:21:23 +00:00

Author

Owner

Verified against each acceptance criterion, before marking this ready.

"The DSN is referenced under the agreed name(s) and nothing
references the retired one." Nothing was retired — the decision was
explicitly that no repository is renamed — so this is checked by
reading both repositories' workflows back rather than by changing them.
ahmad/larda references GLITCHTIP_DSN (repo secret) and maps it to
the VITE_GLITCHTIP_DSN build arg; ahmad/expiro references
VITE_GLITCHTIP_DSN for the bundle and GLITCHTIP_DSN from OpenBao
for the api. Both match the convention this PR records, and neither
needed a change.
The README states the rule a third repository copies, with the
scope, the store and the reason for each of the two names.
markdownlint-cli2@0.23.2 — the pinned version the README lint
step runs — exits 0 on this file.

The remaining criterion is the other repository's, and it is the one
that needed a change: docs/CONFIGURATION.md must say where each value
is actually stored. ahmad/expiro's said variable for a value the API
reports as a secret; corrected in ahmad/expiro#83. ahmad/larda's single
row already describes one secret feeding a build arg and a runtime value,
which is exactly what it does, so it is untouched.

Unverifiable here, and not claimed: "a release of each app still
reaches GlitchTip from both the web bundle and the api." No workflow,
secret or build argument changed in either repository, so nothing can
have broken — but that is an argument from the diff being empty of
behaviour, not an observed event in GlitchTip.

Verified against each acceptance criterion, before marking this ready. - **"The DSN is referenced under the agreed name(s) and nothing references the retired one."** Nothing was retired — the decision was explicitly that no repository is renamed — so this is checked by reading both repositories' workflows back rather than by changing them. `ahmad/larda` references `GLITCHTIP_DSN` (repo secret) and maps it to the `VITE_GLITCHTIP_DSN` build arg; `ahmad/expiro` references `VITE_GLITCHTIP_DSN` for the bundle and `GLITCHTIP_DSN` from OpenBao for the api. Both match the convention this PR records, and neither needed a change. - **The README states the rule a third repository copies**, with the scope, the store and the reason for each of the two names. - **`markdownlint-cli2@0.23.2`** — the pinned version the README lint step runs — exits **0** on this file. **The remaining criterion is the other repository's**, and it is the one that needed a change: `docs/CONFIGURATION.md` must say where each value is actually stored. `ahmad/expiro`'s said `variable` for a value the API reports as a secret; corrected in ahmad/expiro#83. `ahmad/larda`'s single row already describes one secret feeding a build arg and a runtime value, which is exactly what it does, so it is untouched. **Unverifiable here, and not claimed:** "a release of each app still reaches GlitchTip from both the web bundle and the api." No workflow, secret or build argument changed in either repository, so nothing can have broken — but that is an argument from the diff being empty of behaviour, not an observed event in GlitchTip.

ahmad changed title from ~~WIP: docs: Record how the error-reporting DSN is named~~ to docs: Record how the error-reporting DSN is named

2026-09-09 10:21:23 +00:00

ahmad_bot approved these changes

2026-09-09 12:16:27 +00:00

ahmad_bot left a comment

Approved. The convention is worth writing down and it matches what the fleet already does — I checked rather than taking the two precedents named in the description.

Surveyed every repository's workflows for a GlitchTip DSN:

build arg from vars.VITE_GLITCHTIP_DSN     bayan-web, kidpoints, stem, imamah,
                                           namey, trip, khitta, suhba-web   (8)
build arg from secrets.VITE_GLITCHTIP_DSN  expiro                            (1)
build arg from secrets.GLITCHTIP_DSN       larda                             (1)

runtime GLITCHTIP_DSN via app-env          kidpoints, expiro, larda, trip, khitta

So the rule this records is not aspirational: eight of ten already follow it, and the two exceptions are exactly the two the description names. larda mapping its runtime-named secret into the VITE_ build arg is the one I would have expected to be a mistake, and it is not — it is a single-value app doing the sensible thing, which is why "no repository is renamed" is the right decision to attach to this.

The last paragraph earns its place. Saying that a DSN submits and cannot read is what stops the next reader treating "public by construction" as somebody's carelessness and trying to hide it — which would end with the browser value in the vault and the whole distinction collapsed. That is the failure mode the section exists to prevent, so explaining it is not padding.

I would not add adoption counts to the document, for what it is worth: a README states the rule, and 8-of-10 is status that ages. The place for the number is the review and the issue, which is where it now is.

VITE_ being the mechanism rather than a naming choice is the detail that makes the rule non-negotiable, and it is stated. No findings.

Approved. The convention is worth writing down and it matches what the fleet already does — I checked rather than taking the two precedents named in the description. **Surveyed every repository's workflows for a GlitchTip DSN:** build arg from vars.VITE_GLITCHTIP_DSN bayan-web, kidpoints, stem, imamah, namey, trip, khitta, suhba-web (8) build arg from secrets.VITE_GLITCHTIP_DSN expiro (1) build arg from secrets.GLITCHTIP_DSN larda (1) runtime GLITCHTIP_DSN via app-env kidpoints, expiro, larda, trip, khitta So the rule this records is not aspirational: **eight of ten already follow it**, and the two exceptions are exactly the two the description names. `larda` mapping its runtime-named secret into the `VITE_` build arg is the one I would have expected to be a mistake, and it is not — it is a single-value app doing the sensible thing, which is why "no repository is renamed" is the right decision to attach to this. **The last paragraph earns its place.** Saying that a DSN submits and cannot read is what stops the next reader treating "public by construction" as somebody's carelessness and trying to hide it — which would end with the browser value in the vault and the whole distinction collapsed. That is the failure mode the section exists to prevent, so explaining it is not padding. **I would not add adoption counts to the document**, for what it is worth: a README states the rule, and 8-of-10 is status that ages. The place for the number is the review and the issue, which is where it now is. `VITE_` being the mechanism rather than a naming choice is the detail that makes the rule non-negotiable, and it is stated. No findings.

ahmad merged commit 19fa5cde9e into main

2026-09-09 12:43:35 +00:00

ahmad deleted branch feature/64-dsn-naming

2026-09-09 12:43:35 +00:00

ahmad referenced this pull request from a commit

2026-09-09 12:43:35 +00:00

docs: Record how the error-reporting DSN is named (#73)

ahmad referenced this pull request

2026-09-09 12:45:53 +00:00

chore: Settle one name for the GlitchTip DSN across the fleet #64