amtronics/platform-actions

Watch

Fork 0

Document every repository's configuration #71

New issue

Open

opened 2026-09-09 09:17:05 +00:00 by ahmad · 1 comment

ahmad commented

2026-09-09 09:17:05 +00:00

Owner

Context

The org conventions name exactly one trusted source for every environment
variable and secret a project reads: docs/CONFIGURATION.md, linked from
the README, updated in the same pull request that adds or changes a
variable. A pull request introducing a variable without documenting it is
described there as not mergeable.

Surveyed 2026-09-09 against the contents API for every repository on the
server that has .forgejo/workflows/ — not against local checkouts.
Seven have the document; eleven do not:

Has it	Missing it
`Bayan/bayan-web`, `Bayan/kidpoints`, `ahmad/expiro`, `ahmad/larda`, `ahmad/launchpad`, `suhba/khitta`, `suhba/suhba-web`	`Bayan/stem`, `ahmad/imamah`, `ahmad/namey`, `ahmad/portfolio`, `ahmad/trip`, `ahmad/youtube-downloader`, `amtronics/platform-actions`, `suhba/suhba-docs`, `suhba/founding-documents`, `suhba/policies-and-procedures`, `amtronics/infrastructure-vps`

This is not cosmetic. Every one of the repositories missing it reads
Forgejo Actions variables and OpenBao secrets in its workflows —
Bayan/stem alone reads seven variables and a vault path — and the only
record of which exist, what they mean and whether they are required is
the workflow files themselves. That is how a variable gets renamed in one
workflow and left stale in another, which is the shape of
amtronics/platform-actions#64.

Found while adding a notify job to Bayan/stem (Bayan/stem#14), where
there was no document to update. Filed rather than folded in.

Scope

In: adding docs/CONFIGURATION.md to each repository that reads
configuration, listing every variable and secret it actually reads,
with the table the conventions specify — name, type, scope, where it
lives, required, one-line description. Linked from the README.
In: one pull request per repository; the content differs per repository
and a single sweep would be unreviewable.
Out: changing, renaming or consolidating any variable. This records
what exists; amtronics/platform-actions#64 is where a name gets
settled.
Out: the values themselves, which never appear in the document.
Out: repositories that read no configuration — establish that by
reading their workflows rather than assuming it from the repository's
purpose.

Acceptance criteria

Given a repository in scope, when docs/CONFIGURATION.md is read,
then it lists every variable and secret its workflows and compose
files reference, and no variable it does not.
Given that document, when a row is read, then it states name, type,
scope, where the value lives, whether it is required, and a
one-line description — and never a value.
Given the README, when it is read, then it links to the document.
Given a repository with an .env.example, when the two are
compared, then every key appears in both.

### Context The org conventions name exactly one trusted source for every environment variable and secret a project reads: `docs/CONFIGURATION.md`, linked from the README, updated in the same pull request that adds or changes a variable. A pull request introducing a variable without documenting it is described there as not mergeable. Surveyed 2026-09-09 against the contents API for every repository on the server that has `.forgejo/workflows/` — not against local checkouts. Seven have the document; eleven do not: | Has it | Missing it | | --- | --- | | `Bayan/bayan-web`, `Bayan/kidpoints`, `ahmad/expiro`, `ahmad/larda`, `ahmad/launchpad`, `suhba/khitta`, `suhba/suhba-web` | `Bayan/stem`, `ahmad/imamah`, `ahmad/namey`, `ahmad/portfolio`, `ahmad/trip`, `ahmad/youtube-downloader`, `amtronics/platform-actions`, `suhba/suhba-docs`, `suhba/founding-documents`, `suhba/policies-and-procedures`, `amtronics/infrastructure-vps` | This is not cosmetic. Every one of the repositories missing it reads Forgejo Actions variables and OpenBao secrets in its workflows — `Bayan/stem` alone reads seven variables and a vault path — and the only record of which exist, what they mean and whether they are required is the workflow files themselves. That is how a variable gets renamed in one workflow and left stale in another, which is the shape of `amtronics/platform-actions#64`. Found while adding a notify job to `Bayan/stem` (`Bayan/stem#14`), where there was no document to update. Filed rather than folded in. ### Scope - In: adding `docs/CONFIGURATION.md` to each repository that reads configuration, listing every variable and secret it actually reads, with the table the conventions specify — name, type, scope, where it lives, required, one-line description. Linked from the README. - In: one pull request per repository; the content differs per repository and a single sweep would be unreviewable. - Out: changing, renaming or consolidating any variable. This records what exists; `amtronics/platform-actions#64` is where a name gets settled. - Out: the values themselves, which never appear in the document. - Out: repositories that read no configuration — establish that by reading their workflows rather than assuming it from the repository's purpose. ### Acceptance criteria - [ ] Given a repository in scope, when `docs/CONFIGURATION.md` is read, then it lists every variable and secret its workflows and compose files reference, and no variable it does not. - [ ] Given that document, when a row is read, then it states name, type, scope, where the value lives, whether it is required, and a one-line description — and never a value. - [ ] Given the README, when it is read, then it links to the document. - [ ] Given a repository with an `.env.example`, when the two are compared, then every key appears in both.

ahmad added the

labels

2026-09-09 09:17:05 +00:00

ahmad self-assigned this

2026-09-09 14:17:52 +00:00

ahmad added

state/in-progress

and removed

state/ready

labels

2026-09-09 14:17:52 +00:00

ahmad referenced this issue from a commit

2026-09-09 14:20:50 +00:00

docs: Record every variable and secret this repo reads

ahmad added

state/in-review

and removed

state/in-progress

labels

2026-09-09 14:21:57 +00:00

ahmad referenced this issue from a commit

2026-09-09 15:17:56 +00:00

docs: Record every variable and secret this repo reads

ahmad referenced this issue from a commit

2026-09-09 16:47:10 +00:00

docs: Record every variable and secret this repo reads

ahmad referenced this issue from a commit

2026-09-09 17:19:16 +00:00

docs: Record every variable and secret this repo reads

ahmad referenced this issue

2026-09-09 18:17:25 +00:00

docs: Record this repo's configuration and the consumer register #77

ahmad commented

2026-09-09 19:04:45 +00:00

Author

Owner

suhba/founding-documents and suhba/policies-and-procedures are out of scope.
This issue's own carve-out covers them — "repositories that read no
configuration — establish that by reading their workflows rather than assuming
it from the repository's purpose" — and reading them establishes exactly that.

Each has a single workflow, .forgejo/workflows/markdown-lint.yml, which runs
markdownlint-cli against **/*.md with the repository's .markdownlint.json.
Neither file references a secrets.* or a vars.* name. There is no compose
file, no .env.example, no deployment and no image. They are markdown
consumed as git submodules by suhba/suhba-docs, which holds the configuration
for the site that publishes them — documented in suhba/suhba-docs#16.

So there is nothing for a docs/CONFIGURATION.md to say in either, and adding
one would be a document with no rows.

That makes the survey in the body nine repositories rather than eleven, of
which ahmad/youtube-downloader is outside this workspace and
amtronics/infrastructure-vps is out of the board loop's scope. The nine in
scope are done or in review:

Repository	State
`Bayan/stem`	merged
`ahmad/portfolio`	merged
`ahmad/imamah`	merged
`ahmad/trip`	merged (`858e265`)
`ahmad/namey`	`ahmad/namey#79`, ready and green
`amtronics/platform-actions`	`#77`, ready and green
`suhba/suhba-docs`	`suhba/suhba-docs#16`, ready and green
`suhba/founding-documents`	out of scope — reads no configuration
`suhba/policies-and-procedures`	out of scope — reads no configuration

Three PRs are waiting on a review verdict; nothing else is outstanding.

**`suhba/founding-documents` and `suhba/policies-and-procedures` are out of scope.** This issue's own carve-out covers them — "repositories that read no configuration — establish that by reading their workflows rather than assuming it from the repository's purpose" — and reading them establishes exactly that. Each has a single workflow, `.forgejo/workflows/markdown-lint.yml`, which runs `markdownlint-cli` against `**/*.md` with the repository's `.markdownlint.json`. Neither file references a `secrets.*` or a `vars.*` name. There is no compose file, no `.env.example`, no deployment and no image. They are markdown consumed as git submodules by `suhba/suhba-docs`, which holds the configuration for the site that publishes them — documented in `suhba/suhba-docs#16`. So there is nothing for a `docs/CONFIGURATION.md` to say in either, and adding one would be a document with no rows. That makes the survey in the body **nine** repositories rather than eleven, of which `ahmad/youtube-downloader` is outside this workspace and `amtronics/infrastructure-vps` is out of the board loop's scope. The nine in scope are done or in review: | Repository | State | | --- | --- | | `Bayan/stem` | merged | | `ahmad/portfolio` | merged | | `ahmad/imamah` | merged | | `ahmad/trip` | merged (`858e265`) | | `ahmad/namey` | `ahmad/namey#79`, ready and green | | `amtronics/platform-actions` | `#77`, ready and green | | `suhba/suhba-docs` | `suhba/suhba-docs#16`, ready and green | | `suhba/founding-documents` | out of scope — reads no configuration | | `suhba/policies-and-procedures` | out of scope — reads no configuration | Three PRs are waiting on a review verdict; nothing else is outstanding.

ahmad referenced this issue from a commit

2026-09-10 06:33:31 +00:00

docs: Add REGISTRY and correct the partial metrics set

ahmad referenced this issue from a commit

2026-09-10 06:46:51 +00:00

docs: Add the REGISTRY pipeline constant

ahmad referenced this issue from a commit

2026-09-10 07:14:53 +00:00

docs: Add REGISTRY and correct the partial metrics set

ahmad referenced this issue from a commit

2026-09-10 12:15:43 +00:00

docs: Record MIGRATE_SEED_PIN