Skip to content

fix(data-deploy): resolve Pages branding from configs.yml, not the caller - #61

Merged
andrew2net merged 1 commit into
mainfrom
fix/deploy-branding-from-configs
Aug 11, 2026
Merged

fix(data-deploy): resolve Pages branding from configs.yml, not the caller#61
andrew2net merged 1 commit into
mainfrom
fix/deploy-branding-from-configs

Conversation

@andrew2net

Copy link
Copy Markdown
Contributor

Closes the silent-clobber path reported in the cimas-clobbers-deploy-branding hand-off.

The problem

cimas-config/cimas.yml maps .github/workflows/deploy.yml: gh-actions/data/deploy.yml for 29 relaton-data-* repos as a verbatim whole-file copy — Cimas has no variables, no per-repo substitution, no exclusions. Since #59 the per-flavor branding lives in each caller's with: block, so a cimas sync wipes it.

The failure is entirely silent: the Pages site just loses its favicon and description, and nothing goes red. That is why it survived this long. Twelve repos already carry a hand-edited with: block that a sync would revert.

The fix

Branding moves to data-index/configs.yml — already the source of truth for display/favicon/description, but only ever rendered into the Jekyll _config.yml that #58 retired. data-deploy.yml sparse-checks-out relaton/support at its own commit and resolves the three values per flavor, so the caller template carries no with: at all and is safe to sync.

Callers that still pass an input keep winning, so nothing breaks on merge. The three inputs stay declared — a reusable workflow rejects an undeclared input at parse time, so they could not be removed without breaking existing callers anyway.

source is deliberately not centralised

Twelve repos pin source: git because no released relaton-cli has the index command. Losing that pin fails loudly with Could not find command "index" — unlike branding. Centralising it would trade a loud failure for a silent one. It gets deleted fleet-wide once relaton-cli ships index.

Notable details

  • The support checkout is pinned with job.workflow_sha / job.workflow_repository. Not the github context: a called workflow inherits the caller's, so github.workflow_ref names the data repo's own deploy.yml. And github.job_workflow_sha is an OIDC token claim, not a context property — an unknown property evaluates to null rather than erroring, so it would have silently resolved ref: to support's default branch. Green build, wrong favicon: the exact failure class this PR removes. GitHub documents this pair for reusable workflows checking out their own source.
  • --title moved into env:. ${{ }} is raw text substitution before bash parses the line. Acceptable while the value came from the caller's own file; not now that it comes from this repo.
  • $GITHUB_OUTPUT uses the heredoc form with a fresh random delimiter per value. name=value truncates at the first newline, which would let a configs.yml description define arbitrary step outputs.
  • relaton-data-iana's favicon/description are recorded here. Nothing in this repo held them, so stripping its with: block would have silently swapped in the relaton.org favicon and a generic tagline. This is a new editorial choice, not a recovery — its caller is not pushed anywhere yet.
  • Titles now come from display, so rfcsRFC Index (was RFCS Index), rfcsubseriesRFC Subseries Index, idsInternet-Drafts Index, calconnect/adobe mixed-case. Acronym flavors are unchanged. Also, ids and oasis currently deploy with no branding and will gain their configs.yml values on the next deploy — that is the fix working, but it changes live pages in repos nobody edited.

Guard rails

The hand-off asked for a spec because "the failure mode here is entirely silent".

  • The caller template must pass no inputs, generalised to every Cimas-synced template. Matches parsed scalars, not raw text — deploy.yml legitimately names relaton-data-iana in a comment about the crawler's cron window, which a naive text scan would flag.
  • #branding must agree with #render for every repo, so the two configs.yml consumers cannot drift.
  • bin/index-branding is exercised as a subprocess, so renaming a library method cannot leave the suite green while breaking 29 deploys.

Both template guards were mutation-tested: re-adding a with: block fails them.

ci-spec.yml is new because nothing ran the suite before — every other file in .github/workflows/ here is a workflow_call template for other repos, and ci-lint.yml only lints. Tolerable when these specs guarded static templates; not now that this repo's lib/, bin/ and configs.yml are a runtime dependency of every relaton-data-* Pages build.

Accepted trade-off

relaton/support becomes a runtime dependency of all 29 Pages builds, so a bad configs.yml breaks them at once. Mitigated by resolving before the ~10-minute frontend build, pinning code and data to one commit, asserting the resolver never raises for any repo Cimas syncs deploy.yml into, and wiring the suite into CI.

Testing

bundle exec rake263 examples, 0 failures. Changed YAML parses and is within .yamllint's 140-char limit.

Suggested post-merge smoke test: workflow_dispatch on relaton-data-ids — it has no with: block, so it exercises the central path end to end.

Follow-ups (not in this PR)

  • Hand-offs are queued for the six repos whose branding inputs are now redundant (calconnect, ecma, etsi, gost, w3c, iana); all six verified to resolve byte-identically, so removal is a no-op for the published sites.
  • data-index/README.adoc's opening described the retired Jekyll build; corrected, and the _config.yml / generated/ material is now marked superseded. Actually retiring that path (28 generated files plus Gemfile.deploy) is left out of scope.

…ller

`cimas-config/cimas.yml` maps `.github/workflows/deploy.yml:
gh-actions/data/deploy.yml` for 29 relaton-data-* repos as a verbatim
whole-file copy. Since #59 the per-flavor branding lives in each caller's
`with:` block, so a `cimas sync` wipes it — and that failure is entirely
silent: the page just loses its favicon and description, with nothing red
in CI. Twelve repos already carry a hand-edited `with:` block.

Branding now comes from `data-index/configs.yml`, which was already the
source of truth for these values but was only ever rendered into the
Jekyll `_config.yml` that #58 retired. data-deploy.yml sparse-checks-out
relaton/support at its own commit and resolves title/favicon/description
per flavor, so the caller template carries no `with:` at all and is safe
to sync.

`source` is deliberately left a caller input: no released relaton-cli has
the `index` command, and losing that pin fails loudly with `Could not
find command "index"` — unlike branding. Centralising it would trade a
loud failure for a silent one.

- lib: DataIndexConfig.flavor + #branding (explicit arg > configs.yml >
  default; never raises, so relaton-data-ietf still builds unchanged).
  Private favicon/description become entry_*, and a shared entry_title
  keeps #render and #branding from drifting.
- lib/github_output.rb + bin/index-branding: heredoc $GITHUB_OUTPUT
  encoding with a fresh random delimiter per value. `name=value` would
  truncate at the first newline and let a configs.yml description define
  arbitrary step outputs.
- data-deploy.yml: pins the support checkout with `job.workflow_sha` /
  `job.workflow_repository`. Not the `github` context — a called workflow
  inherits the caller's, and `github.job_workflow_sha` is an OIDC claim
  rather than a property, so it would evaluate to null and silently
  resolve `ref:` to the default branch. Also moves `--title` into `env:`,
  which matters now that the value originates here rather than in the
  calling repo's own file.
- configs.yml: records relaton-data-iana's favicon/description, which
  nothing in this repo held, and documents the favicon convention (the
  SDO's own icon where there is a stable URL, relaton.org otherwise).
- specs: assert the caller template passes no inputs, generalised to
  every Cimas-synced template. Matches parsed scalars rather than raw
  text, since deploy.yml legitimately names relaton-data-iana in a
  comment.
- ci-spec.yml: nothing ran the suite before. That was tolerable when
  these specs only guarded static templates; it is not now that this
  repo's lib/, bin/ and configs.yml are a runtime dependency of every
  relaton-data-* Pages build.
Comment on lines +23 to +34
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: ruby/setup-ruby@v1
with:
# Matches the version data-deploy.yml resolves branding under, so a
# syntax or stdlib difference cannot pass here and fail in a data repo.
ruby-version: "3.4"
bundler-cache: true

- run: bundle exec rake
@andrew2net
andrew2net merged commit aa141a2 into main Aug 11, 2026
6 checks passed
@andrew2net
andrew2net deleted the fix/deploy-branding-from-configs branch August 11, 2026 21:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants