werkator/docs/prs/2026-09-11-PR#51-blank-credentials-do-not-shadow.md

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR-documentation is not maintained along with new PRs — treat it as a snapshot, not as current documentation.

The Problem

On the production instance, five of six repositories reported no commit status to Gitea at all. Nothing had failed, nothing was logged, and the builds themselves were green.

The cause is a placeholder. werkator init wrote every repository's machine config with the credentials spelled out but empty:

git:
  account: ""
  token: ""

The machine layer always wins, so those empty values overrode the instance-wide defaults.git of ~/.werkator.yml (ADR 0009). GiteaClient.isEnabled needs a non-blank git.token, found none, and stayed quiet — publishing a status is non-fatal by design. The one repository that worked was the one whose machine config happened to have no git block.

The defect reproduces itself: tools/remote werkator repo-add runs init, so every repository added to an instance arrives with its inherited credentials already disabled. Adding werkprobe is how it was found.

Non-Goals

• No change to what a setting does when written empty — only credentials are treated as placeholders.
• No new configuration key, and no change to where credentials may be written.
• Repairing the machine configs of a running installation is deployment work, not code; this PR makes the next start repair itself.

The Scenarios

Feature: an unfilled credential does not disable an inherited one

Background

• The instance config ~/.werkator.yml may carry a defaults block that sits below every repository layer (ADR 0009).
• A repository's own layers — project config, applied fragment, machine config — win over it, in that order.
• A credential is git.account or git.token.

Scenario#51.01: A blank credential falls through to the instance defaults

So that a repository added to an instance keeps the credentials it was meant to inherit.

• Given an instance config whose defaults.git carries an account and a token
• and a repository whose machine config writes account: "" and token: ""
• When the configuration is loaded
• Then the effective git.account and git.token are the instance's
  • and the file is named once in a warning, because it still wants fixing

Verified by

• ConfigLoaderTest "a blank credential in a repository layer does not shadow the instance defaults"

Scenario#51.02: A key written without a value counts as blank

So that token: and token: "" mean the same thing, since both are what an unfilled template looks like.

• Given an instance config whose defaults.git carries a token
• and a repository whose machine config writes token: with nothing behind it
• When the configuration is loaded
• Then the effective git.token is the instance's

Verified by

• ConfigLoaderTest "a credential written without a value is as blank as an empty string"

Scenario#51.03: A credential that has a value still wins

So that a repository authenticating as someone else on this machine keeps doing so.

• Given an instance config whose defaults.git carries an account and a token
• and a repository whose machine config sets an account but leaves the token blank
• When the configuration is loaded
• Then the account is the repository's and the token is the instance's — the rule is per key

Verified by

• ConfigLoaderTest "a credential that has a value still wins over the instance defaults"

Scenario#51.04: A blank setting is still a setting

So that "report nowhere" stays sayable.

• Given an instance config whose defaults.gitea.baseUrl names a Gitea
• and a repository whose machine config sets gitea.baseUrl: ""
• When the configuration is loaded
• Then the effective gitea.baseUrl is empty — only credentials are treated as placeholders

Verified by

• ConfigLoaderTest "a blank value that is not a credential still overrides"

Scenario#51.05: Without an instance config nothing changes

So that a single-repository installation behaves exactly as before.

• Given no instance config
• and a repository whose machine config writes token: ""
• When the configuration is loaded
• Then the effective token is empty, and nothing is warned about — there is nothing below to shadow

Verified by

• ConfigLoaderTest "without a home config a blank credential is left alone"

Feature: the template stops asserting what it does not know

Scenario#51.06: init writes the credentials commented out

So that a fresh repository inherits the instance credentials instead of disabling them.

• Given a repository with an https origin
• When werkator init runs
• Then the machine config contains the git block commented out, with the detected account offered inside the comment
  • and loading that repository's configuration yields no git section at all

Verified by

• InitCommandTest "creates config files with auto-detected values"
• InitCommandTest "detects account from https url"

Scenario#51.07: A config file of nothing but comments is a layer that sets nothing

So that the file init now writes can be read at all, and an operator may comment every key out again.

• Given a machine config holding only comments
• When the configuration is loaded
• Then the other layers apply unchanged, and no error is raised

Verified by

• ConfigLoaderTest "a config file of nothing but comments is a layer that sets nothing"

The Solution

Two changes, at the two ends of the defect.

ConfigLoader.withoutBlankCredentials drops a blank git.account/git.token from each repository layer before merging, so it cannot shadow the defaults.git below it, and logs once per file — scoped like checkVersion, so the message names the file to fix. Dropped rather than honoured because a credential is the one kind of value that cannot mean anything when empty: there is no build that wants to authenticate as nobody. Everything else keeps the existing semantics, deliberately — an empty setting can be a choice, and Scenario#51.04 pins that down. This is also what repairs a running installation: the next start inherits correctly without anyone editing a file.

InitCommand no longer writes the git block out with empty values; it writes it commented out, with the detected account offered inside the comment and a line saying why. A template that asserts token: "" is a template that makes a claim it has no basis for.

ConfigLoader.loadFile then had to learn that a file of nothing but comments is a layer that sets nothing: readValue answers such a file with "No content to map due to end-of-input", so it now goes through readTree and treats a missing node as an empty layer — the same thing parseYaml has always done for the branch layer.

Open Questions

• The rule names git.account and git.token explicitly (CREDENTIAL_KEYS) rather than deriving "is a secret" from the schema. A third credential would have to be added there by hand; the alternative — marking secrets in WerkatorConfig — is more machinery than two keys justify today.

Additional Changes

• docs/configuration.md: the layering section now states the credential rule, and the machine-config section says that the block is written commented out and that a comment-only file is a valid layer.
• .claude/skills/architecture/SKILL.md: the configuration section names the rule.

Follow-up PRs

• None. The machine configs of the running instance were repaired by hand when the defect was found; after this PR they would have repaired themselves.