fix(data-deploy): resolve Pages branding from configs.yml, not the caller - #61
Merged
Merged
Conversation
…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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes the silent-clobber path reported in the
cimas-clobbers-deploy-brandinghand-off.The problem
cimas-config/cimas.ymlmaps.github/workflows/deploy.yml: gh-actions/data/deploy.ymlfor 29relaton-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'swith:block, so acimas syncwipes 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 fordisplay/favicon/description, but only ever rendered into the Jekyll_config.ymlthat #58 retired.data-deploy.ymlsparse-checks-outrelaton/supportat its own commit and resolves the three values per flavor, so the caller template carries nowith: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.
sourceis deliberately not centralisedTwelve repos pin
source: gitbecause no released relaton-cli has theindexcommand. Losing that pin fails loudly withCould 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 shipsindex.Notable details
job.workflow_sha/job.workflow_repository. Not thegithubcontext: a called workflow inherits the caller's, sogithub.workflow_refnames the data repo's owndeploy.yml. Andgithub.job_workflow_shais an OIDC token claim, not a context property — an unknown property evaluates to null rather than erroring, so it would have silently resolvedref: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.--titlemoved intoenv:.${{ }}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_OUTPUTuses the heredoc form with a fresh random delimiter per value.name=valuetruncates at the first newline, which would let aconfigs.ymldescription define arbitrary step outputs.relaton-data-iana's favicon/description are recorded here. Nothing in this repo held them, so stripping itswith: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.display, sorfcs→RFC Index(wasRFCS Index),rfcsubseries→RFC Subseries Index,ids→Internet-Drafts Index,calconnect/adobemixed-case. Acronym flavors are unchanged. Also,idsandoasiscurrently deploy with no branding and will gain theirconfigs.ymlvalues 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".
deploy.ymllegitimately namesrelaton-data-ianain a comment about the crawler's cron window, which a naive text scan would flag.#brandingmust agree with#renderfor every repo, so the twoconfigs.ymlconsumers cannot drift.bin/index-brandingis 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.ymlis new because nothing ran the suite before — every other file in.github/workflows/here is aworkflow_calltemplate for other repos, andci-lint.ymlonly lints. Tolerable when these specs guarded static templates; not now that this repo'slib/,bin/andconfigs.ymlare a runtime dependency of everyrelaton-data-*Pages build.Accepted trade-off
relaton/supportbecomes a runtime dependency of all 29 Pages builds, so a badconfigs.ymlbreaks 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 syncsdeploy.ymlinto, and wiring the suite into CI.Testing
bundle exec rake→ 263 examples, 0 failures. Changed YAML parses and is within.yamllint's 140-char limit.Suggested post-merge smoke test:
workflow_dispatchonrelaton-data-ids— it has nowith:block, so it exercises the central path end to end.Follow-ups (not in this PR)
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 plusGemfile.deploy) is left out of scope.