A bot notices a stale entry on bestpractices.dev and gives the links that take in the answers¶
- Status: accepted, amends 0047
- Date: 2026-11-18
Context¶
Decision 0047 said that an update of the blueprint brings each changed answer of .bestpractices.json to every repository, as Save (and continue) 🤖 on a level takes it in. It doesn't. bestpractices.dev reads the file with a confidence of 3.5 and replaces an answer that a project already has only at 4 or more, and a justification stays as it is while its status doesn't change. Its documentation of automation proposals says the same: a proposal fills only an unknown answer, unless the address of the edit page forces it with overrides=.
Release 1.22.0 joined the workflows Secret scan and Dependency review into Quick checks, and the answers of the file link quick-checks.yml since. On 2026-11-18 the public entries of all eight repositories still linked secret-scan.yml, which was gone, and 10 to 96 justifications of each entry differed from the file; nothing noticed, as no workflow and no part of blueprint.py read the entries (#1046). The site has no way to write an entry with a token: a change needs a maintainer who is signed in. It asks for about one request per second at most and refuses a long address: one of about 9,500 characters got 414, one of 7,000 did not.
Options¶
- Correct the words only: the template, the guide and 0047 say that Save fills only unknown answers. Nothing tells a maintainer when an answer of the file changes.
- A bot that writes the entry: the site's API takes no token for it, and a login of a person in a workflow would be a secret of a person in every repository.
- A workflow of its own that reads the entry: a new workflow, its runs and the bot-health bot's runs after them, every week in every repository, for one request.
- A job of the weekly run of Links that reads the entry and keeps one issue with the links of the edit pages, which a maintainer opens while signed in.
Decision¶
Option 4, with the words of option 1:
- Read once a week: the job best practices entry of
links.yml, on its schedule and by hand, runsblueprint.py best-practices. The number of the project comes from the badge of the README, of either series, as the checklist reads it; a repository without the badge asks nothing. It readshttps://www.bestpractices.dev/projects/<number>.jsononce, without a login, through Harden-Runner, which allows only GitHub andwww.bestpractices.dev. - Compare the answers of the file only: each field of
.bestpractices.jsonwith the field of the entry,osps_br_07_01_justificationof the file beingOSPS-BR-07.01_justificationof the entry; a status by its value whatever its case, a justification by its text without the spaces at its ends, as the site strips both. Each link of a differing justification of the entry into the repository, on any branch, is checked against the files of the checkout, without a request. What a maintainer answers on the site and the file leaves out is never reported. - One issue: The answers on bestpractices.dev differ from .bestpractices.json, found by a mark in its text, as the issue of the acceptances that end soon is. It lists each answer that differs or links a file that is gone, with the text to enter, and closes once the entry gives every answer. A site that doesn't answer is a warning, and the issue stays as it is. An issue that would pass the 65,536 characters of GitHub leaves out the texts, which its links carry anyway.
- One link per level:
https://www.bestpractices.dev/en/projects/<number>/<level>/edit?<field>=<answer>&…&overrides=<fields>, for passing, silver, gold and baseline-1 to 3, each with the criteria of its own level fromblueprint/bestpractices-criteria.json, as the site ignores a proposal for another level.overrides=names exactly the fields that the entry answers otherwise; an empty one takes the proposal without it. A status and its justification stay in one link, since the site couples them. A link stays at 8,000 characters or below, and the criteria of a level that need more are split into parts, each of which the site takes on its own, since it leaves the fields that a link doesn't name as they are. - The list of the criteria moves from
tests/data/toblueprint/bestpractices-criteria.json, which every repository gets as.github/blueprint/bestpractices-criteria.json, so that the bot knows the level of each criterion; the tests of 0047 read it from there. - The words: the comment of
template/.bestpractices.json.jinja, the guide, the page of the bots and the checklist say that Save (and continue) 🤖 fills only the questions still open, and that a changed answer comes through the links of the bot's issue. The consequence of 0047 that an update brings a changed answer by itself no longer holds.
Consequences¶
- A stale entry shows within a week of the update that changed the file, and putting it right takes a few clicks per level: the maintainer opens each link while signed in, checks the fields that the form highlights and saves.
- The bot never writes the entry and needs no secret; the issue is the only thing that it changes.
- Each repository with the badge sends one request a week to bestpractices.dev.
- What only a signed-in maintainer can see, that the site takes a forced justification whose status doesn't change, rests on the site's code (
apply_url_proposalsofprojects_controller.rb) until a maintainer has saved one such link.